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Preface  What's  in  this  volume 


This  third  volume  of  the  Apple  IIGS  Toolbox  Reference  contains  new 
material  describing  numerous  changes  to  the  Apple  IIGS®  Toolbox.  There 
are  six  previously  undocumented  tool  sets,  many  new  tool  calls,  and 
numerous  corrections  and  additions.  This  document  comprises  both  new 
material  and  information  issued  in  a  previous  update  that  was  available 
only  from  APDA™  (the  Apple  Programmers  and  Developers  Association). 
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Organization 

Like  the  first  two  volumes  of  the  Apple  IlGS  Toolbox  Reference,  this  book  contains  chapters 
that  are  devoted  to  individual  tool  sets  or  managers.  The  chapters  are  arranged 
alphabetically  by  tool  set  name.  Chapters  documenting  the  six  new  tool  sets  appear  in 
alphabetical  order  among  the  other  chapters.  Chapters  that  discuss  previously  existing 
tool  sets  or  managers  carry  the  same  titles  as  before,  with  the  addition  of  the  word 
Update.  Note  that  chapters  in  this  book  have  been  numbered  sequentially  following  the 
last  chapter  in  Volume  2  of  the  Toolbox  Reference. 

Each  chapter  contains  a  brief  introductory  note,  which  indicates  whether  the  chapter 
updates  existing  material  or  describes  a  new  tool  set  or  manager.  Update  chapters  contain 
one  or  more  of  these  sections: 

Error  corrections     Corrects  errors  in  the  previous  toolbox  documentation 
Clarifications         Provides  additional  information  about  previously  documented 

toolbox  features,  including  bug  fixes 
New  features         Describes  new  tool  set  features 
New  tool  calls        Defines  new  tool  calls 

New  chapters  follow  the  organizational  style  of  the  first  two  volumes. 

In  addition  to  the  chapters  that  discuss  the  various  tool  sets  and  managers,  this  book 
contains  several  appendbces: 

Appendbc  E  ("Resource  Types")  Contains  format  and  content  information  for  all 

defined  Apple  IlGS  resource  types 

Appendix  F  ("Delta  Guide")  Collects  all  corrections  to  and  clarifications  of 

the  previous  volumes  of  the  Toolbox  Reference 
in  a  single  location 


Typographical  conventions 

This  update  largely  obeys  the  typographical  conventions  of  the  Apple  IlGS  Toolbox 
Reference.  New  terms  appear  in  boldface  when  they  are  introduced.  Tool  call  parameter 
names  are  given  in  italics.  Record  field  names,  routine  names,  and  code  listings  appear  in 
the  Courier  font. 

For  the  Beta  draft,  new  or  substantially  changed  text  carries  change  bars. 
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Call  format 

This  book  documents  tool  calls  for  all  the  new  tool  sets  and  several  of  the  existing  tool 
sets. 

Certain  elements  of  this  format  may  not  appear  in  all  alls.  For  example,  not  all  calls  return 
error  codes,  and  so  not  all  call  descriptions  contain  a  list  of  error  codes.  Similarly,  stack 
diagrams  are  omitted  from  those  calls  that  do  not  affect  the  stack. 


ToolCallName  $callnumber 

A  description  of  the  call's  function. 

Parameters 

Stack  before  call 


Previous  contents 


-  longPamName  - 


wordParmName 


Stack  after  call 


Long— Description  of  longParmName  parameter 
Word— Description  of  wordParmName  parameter 
<— SP 


Previous  contents 


Result 


Long— Description  of  call  result  value  (if  any) 
<— SP 

Errors  $xxxx      Error  name  Description  of  the  error  code 

C  The  C  language  function  declaration  for  the  call. 

stackField  Detailed  description  of  stack  input  or  output  parameter,  where 

appropriate. 
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Indexes 

Volume  3  contains  three  indexes.  First,  there  is  an  index  of  calls  that  are  new  in  this 
update,  arranged  alphabetically.  Next  is  an  index  listing  all  tool  calls,  both  those  in  the 
Apple  JIGS  Toolbox  Reference  2nd  those  documented  in  this  volume.  This  index  is  included 
to  make  it  easier  to  find  a  particular  call's  description,  whether  it  is  a  new  call  or  one  that 
was  previously  documented.  Finally,  there  is  a  general  index  covering  both  this  book  and 
the  first  two  volumes  of  the  Apple  IIGS  Toolbox  Reference. 

Note  that  the  Beta  draft  only  has  a  single  index,  covering  the  contents  of  Volume  3. 
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Chapter  26  Apple  Desktop  Bus  Tool  Set  Update 


This  chapter  contains  new  information  about  the  Apple®  Desktop  Bus' 
Tool  Set.  The  complete  reference  to  this  tool  set  is  in  Volume  1, 
Chapter  3  of  the  Apple  IIGS  Toolbox  Reference. 
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Error  correction 


The  parameter  table  for  the  ReadKeyMicroData  tool  call  ($0A09)  in  Volume  1  of  the 
Toolbox  Reference  incorrectly  describes  the  format  for  the  readconf  ig  command  ($0B). 
The  description  should  be  as  follows. 


Command 


dataLength 


Name 


Action 


$0B  3  readConf  ig   Read  configuration;  dataPlr  refers  to  a 

3-byte  data  structure: 
Byte    ADB  keyboard  and  mouse 
addresses 

low  nibble  -  keyboard 
high  nibble  -  mouse 
Byte    Keyboard  layout  and  display 
language 

low  nibble  -  keyboard  layout 
high  nibble  -  display  language 
Byte    Repeat  rate  and  delay 
low  nibble  -  repeat  rate 
high  nibble  -  repeat  delay 

The  description  of  this  configuration  record  is  also  wrong  in  the  tool  set  summary.  The 
following  table  shows  the  correct  information. 


Name 


Offset 


Type 


Definition 


ReadConf  igRec  (configuration  record  for  ReadKeyMicroData) 
rcADBAddr  $0000 


rcLayoutOrLang 


rcRepeatDelay  $0002 


Byte 


$0001 


Byte 


ADB  keyboard  and  mouse  addresses 
low  nibble  -  keyboard 
high  nibble  -  mouse 
Byte  Keyboard  layout  and 

display  language 
low  nibble  -  keyboard  layout 
high  nibble  -  display  language 
Repeat  rate  and  delay 
low  nibble  -  repeat  rate 
high  nibble  -  repeat  delay 
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Clarification 

This  section  presents  new  information  about  the  AsyncADBReceive  call. 

You  can  call  AsyncADBReceive  to  poll  a  device  using  register  2,  and  it  will  return  certain 
useful  information  about  the  status  of  the  keyboard.  The  call  returns  the  following 
information  in  the  specified  bits  of  register  2: 


Bit  5: 

0-Caps  Lock  key  down 

1-Caps  Lock  key  up 

Bit  3: 

0-Control  key  down 

1 -Control  key  up 

Bit  2: 

0-Shift  key  down 

1-Shift  key  up 

Bit  1: 

0-Option  key  down 

1-Option  key  up 

Bit  0: 

0-Command  key  down 

1-Command  key  up 
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Chapter  27  Audio  Compression  and 
Expansion  Tool  Set 


This  chapter  dcxuments  the  features  of  the  new  Audio  Compression  and 
Expansion  (ACE)  Tool  Set.  This  is  a  new  tool  set,  not  previously 
documented  in  the  Apple  IIGS  Toolbox  Reference. 
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Error  correction 

This  is  a  note  to  call  to  your  attention  an  error  in  the  Apple  IIGS  Toolbox  Reference  Update 
(distributed  by  APDA™).  The  description  for  the  ACEExpand  tool  call  carried  an 
incorrect  parameter  block.  This  book  contains  a  corrected  description. 


About  Audio  Compression  and  Expansion 

The  Audio  Compression  and  Expansion  (ACE)  tools  are  a  set  of  utility  routines  that 
compress  and  expand  digital  audio  data.  The  tool  set  is  designed  to  support  a  variety  of 
methods  of  audio  signal  compression,  but  at  present  only  one  method  is  implemented. 

With  the  present  method  of  compression  supported  by  the  ACE  tools,  you  can  choose 
either  of  two  compression  ratios.  You  can  compress  a  digital  audio  signal  to  half  its 
original  size  or  to  three-eighths  its  original  size.  The  ratio  used  is  determined  by  a 
parameter  of  the  ACE  call  that  does  the  compression  or  expansion. 

The  obvious  advantages  of  compressing  an  audio  signal  are  that  it  takes  up  less  space  on 
the  disk,  and  less  time  is  needed  to  transfer  die  data.  A  digital  sample  that  is  compressed 
to  half  its  original  size  occupies  only  half  the  space  and  takes  only  half  as  long  to  transfer. 
Such  a  sample  can  load  from  the  disk  twice  as  fast  as  the  uncompressed  version,  and  is 
much  more  economical  to  upload  to  or  download  from  a  commercial  computer  network. 
Note,  however,  that  data  compression  and  expansion  requires  significant  processor 
resources,  and  therefore  takes  some  time. 
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Uses  of  the  ACE  Tool  Set 

Software  often  includes  sound  effects,  music,  or  speech.  The  problem  with  digitized 
sound  is  that  it  requires  considerable  storage  space.  A  faithful  monophonic  digitization 
of  30  seconds  of  an  FM  radio  signal  occupies  neariy  a  megabyte  (MB)  of  disk  space.  A  user 
might  be  somewhat  reluctant  to  use  a  program  that  occupies  so  much  space  only  to 
achieve  sound  effects.  The  ACE  Tool  Set  provides  you  with  the  means  to  compress 
digitized  sound  signals  to  minimize  this  problem. 

ACE  presently  supports  Adaptive  Differential  Pulse  Code  Modulation  (ADPCM).  This 
compression  method  assumes  that  audio  signals  tend  to  be  relatively  smooth  and 
continuous.  If  the  amplitude  (loudness)  of  a  typical  audio  signal  is  plotted  against  time, 
the  graph  is  relatively  smooth  compared  to  a  spreadsheet,  a  text  document,  or  other 
typical  files  that  may  contain  arbitrarily  distributed  byte-values.  As  a  result,  it  is  possible 
to  compute  the  probable  value  of  the  next  sample  in  the  signal.  ADPCM  uses  a  static 
model  of  what  the  change  between  any  given  value  and  the  next  might  likely  be  and  a 
dynamic  model  of  what  the  next  actual  change  should  be,  based  on  the  values  last 
observed.  It  examines  the  next  signal  to  compare  its  predictions  against  the  observed 
value,  and  then  encodes  the  difference  between  its  prediction  and  the  actual  value. 

ADPCM  relies  on  the  relative  predictability  of  audio  signals.  If  the  changes  in  an  audio 
signal  are  too  great  or  sudden,  the  value  that  ADPCM  records  will  be  erroneous.  In  general, 
there  is  a  cerain  statistically  predictable  amount  of  error  that  appears  in  any  signal  that  is 
compressed  by  this  method.  The  errors  appear,  not  as  distortions  of  the  quality  of  the 
sound,  but  as  pink  noise,  or  hiss,  much  like  the  hiss  on  ordinary  cassette  recordings.  Thus, 
aldiough  ADPCM  compression  is  suitable  for  many  sound  compression  tasks,  particularly 
for  sound  effects  or  speech  in  games  or  business  software,  it  is  not  the  best  choice  for 
very  high-fidelity  reproduction.  A  signal  compressed  by  the  ADPCM  method  will  likely  be 
too  noisy  for  use  in  professional  audio,  such  as  film  soundtrack  recording. 
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How  ADPCM  works 

The  ADPCM  method  assumes  that  any  particular  digital  sample  in  a  block  of  audio  data 
has  a  value  that  is  relatively  close  to  those  on  either  side  of  it.  In  fact,  the  noise  in  the 
reproduced  signal  arises  from  samples  that  vary  more  than  the  method  supports.  ADPCM 
predicts  what  the  next  value  will  be,  and  compares  it  with  the  value  that  is  actually  there. 
The  difference  is  encoded  in  a  value  that  is  some  number  of  bits  in  size,  that  size  being 
specified  by  the  application  code.  With  ADPCM  the  programmer  can  specify  encoded 
values  either  3  or  4  bits  wide.  Since  the  original  data  is  stored  in  8-bit  samples,  the 
compression  rate  is  either  8  to  3  or  8  to  4,  depending  on  which  size  a  particular  program 
specifies. 

Errors  result  when  the  difference  between  the  original  signal  and  the  value  that  ADPCM 
predicts  is  greater  than  can  be  encoded  in  the  specified  number  of  bits.  The  encoded 
value  then  effectively  becomes  a  random  value,  and  so  is  perceived  as  audio  noise.  If  the 
target  code  is  3  bits  wide,  then  the  difference  observed  by  the  compression  algorithm  is 
more  likely  to  be  out  of  range  than  if  the  code  size  is  4  bits.  Greater  compression 
therefore  results  in  greater  loss  of  fidelity. 

As  stated  earlier,  the  fidelity  loss  sounds  like  hiss,  not  like  a  gross  distortion  of  the  audio 
signal.  Even  using  inaccurate  predictive  models,  ADPCM  tends  to  produce  hiss  rather  than 
more  offensive  forms  of  distortion.  The  technique  tracks  the  gross  characteristics  of 
audio  signals  well  even  when  the  rate  of  errors  is  high.  At  worst,  an  expanded  signal  sounds 
faithful  to  the  original,  though  muffled  by  noise. 

A  Important     The  noisier  a  sampled  signal  is,  the  noisier  the  sample  compressed  by 
using  ADPCM  will  be.  Any  noise  that  is  introduced  into  the  signal 
produces  discontinuities  in  the  audio  data  and  causes  errors  in  the 
compression  and  expansion  process.  For  this  reason,  any  editing, 
equalization,  or  other  sound-processing  effects  should  be  applied  to 
the  original  signal  before  it  is  compressed.  ADPCM  compression 
should  be  the  last  process  applied  to  an  audio  signal  before  it  is  stored 
on  the  final  disk,  a 
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ACE  housekeeping  routines 

These  routines  allow  you  to  start  and  stop  the  ACE  tools  and  to  obtain  tool  set  status 
information. 

ACEBootlnit  $011D 

Performs  any  initializations  of  the  ACE  tools  that  are  necessary  at  boot  time. 

▲  Warning      Applications  must  not  make  this  call.  ▲ 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  None 

C  extern  pascal  void  ACEBootlnit () ; 
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ACEStartUp  $021D 

Initializes  the  ACE  tools  for  use  by  an  application.  ACEStartup  sets  aside  a  region  of 
bank  $00,  specified  by  dPageAddr,  for  use  as  the  ACE  tools'  direct  page.  At  present,  ACE 
uses  one  256-byte  page  of  bank  $00  memory  as  its  direct  page.  Future  versions  of  the  ACE 
tools  may  use  a  different  amount  of  memory  for  the  direct  page,  so  applications  should 
determine  the  correct  size  for  the  direct  page  with  a  call  to  ACEinf  o.  The  tool  set's  direct 
page  should  always  begin  on  a  page  boundary. 

Parameters 

Stack  before  call 


Previous  contents 


dPageAddr 


Word— Bank  $0  starting  address  of  direct-page  space 
<— SP 


Stack  after  call 


PreiAous  contents 


Errors 


$1D01 
$1D02 


<— SP 

acelsActive 
aceBadDP 


ACE  Tool  Set  already  started  up. 
Requested  direct-page  location 
invalid. 


extern  pascal  void  ACEStartUp (dPageAddr) ; 
Word  dPageAddr; 
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ACEShutDown  $031D 

Performs  any  housekeeping  that  is  required  to  shut  down  the  ACE  Tool  Set.  Applications 
that  use  the  ACE  tools  should  always  make  this  call  before  quitting.  The  application,  not 
the  ACE  Tool  Set,  must  allocate  and  deallocate  direct-page  space  in  bank  zero. 

Parameters        This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  $1D03      aceNotActive  ACE  Tool  Set  not  started  up. 

C  extern  pascal  void  ACEShutDown () ; 
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ACEVersion  $04lD 

Returns  the  version  number  of  the  currently  installed  ACE  Tool  Set.  This  call  can  be  made 
before  a  call  to  ACEStartup.  The  versionlnfo  result  will  contain  the  information  in  the 
standard  format  defined  in  Appendix  A,  "Writing  Your  Own  Tool  Set,"  in  Volume  2  of  the 
Toolbox  Reference. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


versionlnfo 


Word— Version  number  of  ACE  Tool  Set 


<— SP 


Errors 


None 


C 


extern  pascal  Word  ACEVersion () ; 
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ACEReset  $051D 

Resets  the  ACE  Tool  Set.  This  call  is  made  by  a  system  reset. 

A  Warning     Applications  should  never  make  this  call  because  it 
performs  tool  set  initializations  appropriate  to  a 
machine  reset,  a 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  None 

C  extern  pascal  void  ACEReset {); 
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ACEStatus  $06lD 

Returns  a  Boolean  flag,  which  is  TRUE  (nonzero)  if  the  tool  set  has  been  started  up,  and 
FALSE  (zero)  if  it  has  not.  This  call  can  be  made  before  a  call  to  ACEStartup. 

♦  Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  ACEStatus,  your  program  need  only  check  the 
value  of  the  returned  flag.  If  the  ACE  Tool  Set  is  not  active,  the  returned  value  will  be 
FALSE  (NIL). 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


PreiHous  contents 


activeFlag 


Word— Boolean  value  indicating  whether  tool  set  is  active 


<— SP 


Errors 


None 


C 


extern  pascal  Word  ACEStatus () ; 
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ACEInfo  $071D 


Returns  certain  information  about  tiie  currently  installed  version  of  the  ACE  tools.  This  call 
can  be  made  before  a  call  to  ACEStartup.  The  infoItemCode  parameter  specifies  what 
information  the  call  is  to  return.  At  present,  the  only  valid  value  is  0.  This  value  specifies 
that  the  call  will  return  the  size  in  bytes  of  the  direct  page  that  ACE  requires. 

Parameters 

Stack  before  call 

Previous  contents 

Space       -  Long— Space  for  result 

infoItemCode  Word— What  type  of  information  to  return 

<— SP 

Stack  after  call 


Previous  contents 


-  infoItemValue  - 


Long— Requested  information 
<— SP 


Errors 


$1D04  aceNoSuchParam 
extern  pascal  LongWord  ACEInfo (infoItemCode) ; 


Requested  information  type  not 
supported. 


Word  infoItemCode; 
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Audio  Compression  and  Expansion  tool  calls 

The  Audio  Compression  and  Expansion  tool  calls  are  all  new  calls,  added  to  the  Apple  IIGS 
Toolbox  since  the  first  two  volumes  of  the  Apple  IIGS  Toolbox  Reference  were  published. 


ACECompBegin  $0B1D 

Prepares  the  ACE  tools  to  compress  a  new  audio  sequence.  After  ACECompress 
completes  the  process  of  compression  and  returns,  the  ACE  tools  normally  save  certain 
relevant  state  information  so  that  subsequent  calls  to  ACECompress  can  be  used  on 
succeeding  parts  of  the  same  audio  sequence.  It  is  often  desirable  to  break  a  long  audio 
signal  into  smaller  parts  for  compression.  The  preservation  of  appropriate  state  variables 
allows  a  call  to  ACECompress  to  compress  part  of  such  a  signal  and  then,  for  a 
subsequent  call,  to  continue  the  compression  process  where  the  previous  call  left  off. 

Just  before  a  program  calls  ACECompress  to  process  a  new  audio  sample,  it  should  call 
ACECompBegin  to  ensure  that  all  saved  state  information  is  cleared  and  that 
ACECompress  is  Starting  with  a  "clean  slate."  When  an  application  is  compressing  a  long 
audio  sample  as  a  number  of  smaller  pieces,  it  should  call  ACECompBegin  only  before  the 
first  subsequence.  Thereafter,  the  application  should  not  make  this  call  until  all  parts  of 
the  sequence  have  been  processed.  The  state  information  that  ACE  preserves  between 
calls  allows  ACECompress  to  process  subsequent  blocks,  using  appropriate  information 
from  previous  ones. 

Call  ACECompBegin  only  before  compressing  the  first  sequence  of  a  series  of  sub- 
sequences, or  before  compressing  a  single  sequence  that  is  not  part  of  a  longer  sequence. 

Parameters        This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  $1D03      aceNotActive  ACE  Tool  Set  not  started  up. 

C  extern  pascal  void  ACECompBegin ()  ; 
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ACECompress  $091D 

Compresses  a  number  of  blocks  of  digital  audio  data'and  stores  the  compressed  data  at  a 
specified  location.  Each  input  block  contains  512  bytes  of  data  to  be  compressed.  Your 
program  also  specifies  the  compression  method,  using  the  method  parameter. 

Before  issuing  the  ACECompress  tool  call,  your  program  should  call  ACECompBegin  to 
prepare  the  ACE  Tool  Set  for  audio  compression. 


♦  Note:  Because  ACECompress  is  guaranteed  to  reduce  the  size  of  every  byte  of  source 
data,  the  resulting  data  can  be  stored  in  the  same  place  as  the  source  data.  That  is,  the 
source  and  destination  locations  in  RAM  can  be  the  same. 


Parameters 

Stack  before  call 


Prmous  contents 


src 


srcOffset 


dest 


destOjJset 


nBlks 


method 


Stack  after  call 


Previous  contents 


Errors 


$1D05 

$1D06 
$1D07 
$1D08 


Long— Handle  to  the  source  data 

Long— Offset  from  src  to  the  actual  storage  location 

Long— Handle  to  storage  for  the  resulting  data 

Long— Offset  from  dest  to  the  actual  storage  location 

Word— Number  of  512-byte  blocks  of  source  data 
Word— Method  of  compression 
<— SP 


<— SP 
aceBadMethod 

aceBadSrc 

aceBadDest 

aceDataOverlap 


Specified  compression  method 
not  supported. 
Specified  source  invalid. 
Specified  destination  invalid. 
Specified  source  and  destination 
areas  overlap  in  memory. 
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C  extern  pascal  void  ACECompress (src,   srcOffset,  dest, 

destOffset,  nBlks,  method)  ; 

Handle        src,  dest; 

Long  srcOffset,  destOffset; 

Word  nBlks,  method; 

src,  dest  Contain  handles  to  source  and  destination  data  locations, 

respectively. 

srcOffset,  destOffset  Contain  byte  offsets  from  locations  specified  by  src  and  dest, 

respectively.  These  parameters  allow  your  program  to  position  within 
an  input  sample  or  output  buffer. 

nBlks  Specifies  the  number  of  512-byte  blocks  of  audio  data  to  be 

compressed. 

method  Specifies  the  compression  method  to  be  used  by  ACECompress 

when  processing  the  data.  A  value  of  1  causes  each  byte  of  input  data 
to  be  compressed  to  a  4-bit  quantity;  a  value  of  2  yields  3  bits  per 
byte  of  input  data. 

Clearly,  the  value  of  the  method  parameter  helps  determine  the  size  of 
the  resulting  data  that  ACECompress  stores  at  destOffset  bytes 
beyond  the  location  specified  by  dest.  When  using  method  1  (4-bit 
compression),  you  can  calculate  the  number  of  bytes  ACECompress 
will  produce  by  multiplying  the  contents  of  the  nBlks  parameter  by  the 
number  of  bytes  in  a  data  block  (512),  multiplying  that  result  by  the 
number  of  result  bits  per  input  byte  (4),  and  then  dividing  by  the 
number  of  bits  in  a  byte  (8).  Expressed  as  a  formula,  the  calculation 
would  be 

(inBlks*  512)*  4)/ 8 

For  method  2,  the  same  basic  calculation  applies,  except  that  each 
input  byte  results  in  3  output  bits 

((nBfc*512)*3)/8 
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ACEExpand  $0A1D 

Expands  a  previously  compressed  audio  sample,  using  the  method  specified  by  the 
we/ZiOi/ parameter,  and  stores  it  at  the  specified  location.  UnEke  ACECompress, 
ACEExpand  cannot  store  its  results  in  the  same  location  as  its  source  since  the  resulting 
data  is  2  to  2.67  times  as  large  as  the  source. 

Parameters 

Stack  before  call 


Previous  contents 


src 


srcOffset 


dest 


destOffset 


nBlks 


method 


Stack  after  call 


Long— Handle  to  the  source  data 

Long— Offset  from  src  to  the  actual  storage  location 

Long— Handle  to  storage  for  the  resulting  data 

Long — Offset  from  dest  to  the  actual  storage  location 

Word— Number  of  512-byte  blocks  to  be  stored  at  dest 
Word— Method  of  compression 
<— SP 


Previous  contents 


<— SP 
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Errors  $1D05      aceSadMethod  Specified  compression  method 

not  supported. 

$1D06      aceBadSrc  Specified  source  invalid. 

$1D07      aceBadDest  Specified  destination  invalid. 

$1D08      aceDataOveriap         Specified  source  and  destination 

areas  overlap  in  memory. 

C  extern  pascal  void  ACEExpand (src,   srcOffset,  dest, 

destOff set,  nBlks,  method) ; 

Handle        src,  dest; 

Long  srcOffset,  destOffset; 

Word  nBlks,  method; 

src,  dest  Contain  handles  to  source  and  destination  data  locations, 

respectively. 

srcOffset,  destOffset  Contain  byte  offsets  from  locations  specified  by  src  and  dest, 

respectively.  These  parameters  allow  your  program  to  position  within 
the  input  compressed  data  or  output  buffer. 

nBlks  Specifies  the  number  of  512-byte  blocks  of  expanded  data  to  be 

returned  at  the  location  destOffset  bytes  beyond  dest. . 

method  Specifies  the  method  used  when  the  sample  was  compressed.  A  value 

of  1  indicates  that  ACEExpand  is  to  expand  each  4-bit  quantity  in  the 
compressed  sample  into  an  8-bit  byte.  A  value  of  2  causes 
ACEExpand  to  proccss  3-bit  quantities  in  the  compressed  sample. 
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ACEExpBegin  $0C1D 

Prepares  ACE  to  expand  a  new  sequence.  Like  ACECompsegin,  ACEExpBegin  clears  any 
stored  state  information  from  previous  calls  to  expand  compressed  data.  You  can  expand 
a  large  compressed  sample  by  processing  it  as  a  series  of  subsequences  with  repeated  calls 
to  ACEExpand,  because  certain  appropriate  state  variables  are  preserved  from  call  to 
call.  If  you  are  calling  ACEExpand  to  work  on  a  new  sequence  that  bears  no  relation  to  any 
other  compressed  sequence,  or  to  expand  a  short  sequence  in  just  one  call  to 
ACEExpand,  you  should  make  this  call  first  to  clear  these  state  variables.  If,  on  the  other 
hand,  you  are  making  a  call  to  ACEExpand  to  expand  a  sequence  that  is  a  part  of  a  longer 
sequence  and  is  not  the  first  subsequence,  you  should  not  make  this  call  first,  because  it 
will  throw  away  all  information  that  ACE  has  recorded  about  the  previous  sequences. 

Parameters        This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  $1D03      aceNotActive  ACE  Tool  Set  not  started  up. 

C  extern  pascal  void  ACEExpBegin {) ; 
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ACE  Tool  Set  error  codes 

This  section  lists  the  enor  codes  that  may  be  returned  by  Audio  Compression  and  Expansion  Tool  Set 


calls. 

Value 

Name  Definition 

$1D01 

acelsActive 

ACE  Tool  Set  already  started  up. 

$1D02 

aceBadDP 

Requested  direct-page  location  invalid. 

$1D03 

aceNotActive 

ACE  Tool  Set  not  started  up. 

$1D04 

aceNoSuchParam 

Requested  information  type  not  supported. 

$1D05 

aceBaciMethod 

Specified  compression  method  not  supported. 

$1D06 

aceBadSrc 

Specified  source  invalid. 

$1D07 

aceBadDest 

Specified  destination  invalid. 

$1D08 

aceDataOverlap 

Specified  source  and  destination  areas  overiap 

in  memory. 
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Chapter  28  Control  Manager  Update 


This  chapter  documents  new  features  of  and  information  about  the 
Control  Manager.  The  complete  Control  Manager  documentation  is  in 
Volume  1,  Chapter  4  of  the  Toolbox  Reference. 
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Error  corrections 

This  section  documents  errors  in  Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox 
Reference. 

■  The  color  table  for  the  size  box  control  in  the  Toolbox  Reference  is  incorrect.  The 
correct  table  follows,  with  new  information  in  boldface. 


growOutline  word 

Color  of  size  box's  outline 

Bits  8-15 

"  zero 

Bits  4-7 

=  outline  color 

Bits  0-3 

•=  zero 

growNorBack  WOrd 

Color  of  interior  when  not  highlighted 

Bits  8-15 

•=  zero 

Bits  4-7 

"  background  color 

Bits  0-3 

-  icon  color 

growSelBack  WOrd 

Color  of  Interior  when  highlighted 

Bits  8-15 

=  zero 

Bits  4-7 

'  background  color 

Bits  0-3 

=  icon  color 

■  On  page  4-76  of  the  Toolbox  Reference,  in  the  section  that  covers  the  setctiParams 
call,  it  states  that  the  call  "Sets  new  parameters  to  the  control's  definition 
procedure . . This  description  is  misleading;  the  call  does  not  directly  set  the 
parameters.  Rather,  it  sends  the  new  parameters  to  the  control's  definition  procedure, 
unlike  Setctivaiue,  which  actually  sets  the  appropriate  value  in  the  control  record 
and  then  passes  the  value  on  to  the  definition  procedure. 
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Clarifications 

The  following  items  provide  additional  information  about  features  previously  described 
in  the  Toolbox  Reference. 

m  The  barArrowBack  entry  in  the  scroO  bar  table  was  never  implemented  as  first 
intended,  and  is  now  no  longer  used. 

■  The  Control  Manager  preserves  the  current  port  across  Control  Manager  calls,  including 
those  that  are  passed  through  other  tools,  such  as  the  Dialog  Manager. 

■  The  Control  Manager  preserves  the  following  fields  in  the  port  of  a  window  that 


contains  controls: 

bkPat 

background  pattern 

pnLoc 

pen  location 

pnSize 

pen  size 

pnMode 

pen  mode 

pnPat 

pen  pattern 

pnMask 

pen  mask 

pnVis 

pen  visibility 

f ontHandle 

handle  of  current  font 

fontID 

ID  of  current  font 

f ontFlags 

font  flags 

txSize 

text  size 

txFace 

text  face 

txMode 

text  mode 

spExtra 

value  of  space  extra 

chExtra 

value  of  character  extra 

fgColor 

foreground  color 

bgColor 

background  color 

■  The  control  definition  procedures  for  simple  buttons,  check  boxes,  and  radio  buttons 
can  now  compute  the  size  of  their  boundary  rectangles  automatically.  The  computed 
size  is  based  on  the  size  of  the  title  string  for  the  button. 

■  To  ensure  predictable  color  behavior,  you  should  always  align  color  table-based 
controls  on  an  even  pixel  boundary  in  640  mode.  If  you  do  not  do  so,  the  control  will 
not  appear  in  the  colors  you  specify,  due  to  the  effect  of  dithering. 
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New  features  in  the  Control  Manager 

The  Control  Manager  now  supports  a  number  of  new  features.  This  section  discusses  these 
new  features  in  detail. 

■  Colors  in  control  tables  now  use  all  four  color  bits  in  both  modes;  they  formerly  used 
only  2  bits  in  640  mode.  This  change  affects  all  control  color  tables  defined  in  the 
Toolbox  Reference.  For  any  applications  that  use  color  controls  in  640  mode,  the  effect 
is  that  controls  will  be  a  different  color.  This  change  was  made  so  that  dithered  colors 
can  be  used  with  controls. 

■  The  scroll  bar  control  definition  procedure  now  maintains  the  required  relationship 
among  the  ctivaiue,  viewsize,  and  datasize  fields  of  a  scroll  bar  record.  Prior 
to  Apple  UGS  System  Software  5.0,  it  was  the  responsibility  of  the  application  to  ensure 
that  the  ctivaiue  field  never  exceeded  the  difference  between  datasize  and 
viewSize  (dataSize  -  viewSize^.  The  scroll  bar  control  definition  procedure  now 
adjusts  the  ctivaiue  or  datasize  field  if  the  other  quantities  are  set  to  invalid 
values. 

For  example,  if  viewSize  =  30  and  datasize  - 100,  then  the  maximum  ctivaiue 
allowed  is  70.  If  an  application  set  the  ctivaiue  field  to  80,  the  Control  Manager 
would  adjust  datasizeto  110.  In  this  same  example,  if  ctivaiue  -  70  and  the 
application  set  datasize  to  90,  the  Control  Manager  would  adjust  ctivaiue  to  60. 

Changes  to  the  viewSize  field  can  also  invalidate  the  three  settings.  In  the  example 
mentioned  before,  in  which  ctivaiue  -  70,  viewSize  -  30,  and  datasize  -  100, 
setting  viewSize  to  40  would  cause  Control  Manager  to  set  ctivaiue  to  60. 


Keystroke  processing  in  controls 

Apart  from  the  normal  use  of  keystrokes  to  enter  data,  the  Control  Manager  now  supports 
two  special  uses  for  keyboard  data:  keystroke  equivalents  and  switching  between 
certain  types  of  controls. 
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Many  types  of  controls  support  keystroke  equivalents,  which  allow  the  user  to  select  the 
control  by  pressing  a  keyboard  key.  You  assign  a  keystroke  equivalent  for  a  control  in  its 
control  template  (see  "New  Control  Manager  templates  and  records"  later  in  this  chapter 
for  specifics  on  control  templates).  When  the  user  presses  that  key,  your  program  receives 
an  event  just  as  if  the  user  had  clicked  in  the  control.  Further,  the  system  will  automatically 
highlight  and  dim  the  control.  Note  that  this  feature  is  only  available  to  controls  that  have 
been  created  wi±  the  NewControi2  tool  call,  and  for  which  the  fctiwantsEvents  bit 
has  been  set  to  1  in  the  moreFiags  word  of  the  control  template.  See  "New  and  changed 
controls"  later  in  this  chapter  for  information  about  which  controls  support  keystroke 
equivalents. 

Edit  field  controls  (LineEdit  controls  and  TextEdit  controls)  accept  keystrokes  as  part  of 
their  normal  function.  Note,  however,  that  there  can  be  more  than  one  edit  field  control  in 
a  window.  Under  these  circumstances,  the  user  moves  among  these  controls  by  pressing 
the  Tab  key.  In  addition,  the  system  must  keep  track  of  which  control  is  meant  to  receive 
user  keystrokes.  To  do  so,  the  Control  Manager  now  supports  the  notion  of  a  target 
control.  The  target  control  is  that  edit  field  control  which  is  the  current  recipient  of  user 
actions  (keystrokes  and  menu  items). 


The  Control  Manager  and  resources 

You  can  now  specify  most  data  for  the  Control  Manager  using  either  pointers,  handles,  or 
resource  E)s  (see  "Chapter  45,  "Resource  Manager,""  in  this  book  for  complete 
mformation  on  resources).  Because  the  form  of  die  specification  may  differ,  die  Control 
Manager  (as  well  as  many  other  tool  sets)  also  requires  a  reference  type,  which  indicates 
whether  a  particular  reference  is  a  pointer,  handle,  or  resource  ID.  You  set  the  reference 
type  and  the  reference  as  appropriate  in  the  control  template  you  pass  to  the  Control 
Manager  NewControi2  tod  call. 

You  can  use  resources  to  store  a  wide  variety  of  items  for  the  Control  Manager.  For 
example,  the  tides  associated  with  simple  buttons,  radio  buttons,  and  check  boxes 
created  with  the  NewControi2  tool  call  may  be  stored  as  resources.  As  a  result,  your 
application  may  free  die  space  devoted  to  die  tide  string  after  die  control  has  been 
created.  Similariy,  you  can  define  control  definition  procedures  as  resources.  The  Control 
Manager  will  load  die  code  when  it  is  needed. 

The  Control  Manager  handles  resources  differendy,  based  upon  die  data's  degree  of 
permanence.  For  temporary  information,  ConU"ol  Manager  loads  die  resource,  uses  the 
data,  and  then  frees  the  resource  (using  die  ReieaseResource  tool  call).  For  permanent 
information,  die  Control  Manager  loads  the  resource  each  time  die  resource  is  accessed.  • 
Such  resources  should  be  unlocked  and  unpurgeable. 
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The  current  version  of  the  Apple  UGS  system  software  keeps  the  control  definition 
procedure  for  icon  button  controls  in  the  system  resource  file.  In  the  future,  the  sytsem 
may  store  other  defProcs  in  this  resource  file.  Consequendy,  you  should  ensure  that  the 
Resource  Manager  can  reach  the  system  resource  file  in  any  resource  search  path  you  set  up 
(see  Chapter  45,  "Resource  Manager,"  later  in  this  book  for  more  information  on  the 
resource  file  search  path). 


New  and  changed  controls 

The  Control  Manager  now  supports  more  standard  control  types.  In  addition  to  the 
original  standard  controls  (buttons,  check  boxes,  radio  buttons,  size  boxes,  and  scroll 
bars),  the  Control  Manager  now  supports  the  following  conti-ols: 

■  Static  text  controls  display  text  messages  in  a  rectangle  that  you  define.  The 
displayed  text  supports  word  wrap  and  character  styling.  This  text  cannot  be  edited 
by  the  user. 

■  Picture  controls  draw  a  picture  into  a  defined  rectangle. 

■  Icon  button  controls  allow  you  to  present  an  icon  as  part  of  a  button  control.  A 
defined  icon  is  displayed  within  die  bounds  of  the  rectangle  that  repicsents  die  button 
control  on  the  screen.  Icon  buttons  include  support  for  keyboard  equivalents. 

■  LineEdit  controls  allow  the  user  to  enter  single-line  items. 

■  TextEdit  controls,  supported  by  the  new  TextEdit  tool  set  (see 

Chapter  49,  TextEdit,"  in  this  book),  allow  the  user  to  edit  text  widiin  a  defined 
rectangle,  which  can  extend  beyond  a  single  line. 

■  Pop-up  menu  controls  support  scrolling  lists  of  possible  selection  options  that 
appear  when  the  user  selects  the  control. 

■  List  controls  display  scrollable  lists  of  items. 

In  order  to  create  any  of  these  new  controls,  you  must  set  up  die  appropriate  control 
template  and  call  NewControi2.  Unlike  the  NewControi  tool  call,  which  accepts  its 
control  definition  on  the  stack,  NewControi2  defines  conu-ols  according  to  die 
contents  of  one  or  more  control  templates.  These  templates  contain  all  die  information 
necessary  for  die  Control  Manager  to  create  controls.  Your  application  fills  each  conti-ol 
template  widi  the  data  appropriate  to  die  control  you  wish  to  create.  The  Conu-ol 
Manager  uses  diis  input  specification  to  constnict  die  corresponding  control  record  and 
create  die  conti-ol.  You  can  use  diis  technique  to  create  any  control,  not  just  die  new 
conti-ol  types.  For  complete  information  on  die  format  and  content  of  diese  conti-ol 
templates,  see  "New  Conti-ol  Manager  templates  and  records"  later  in  tiiis  chapter. 
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All  controls  created  by  NewControi2,  rather  than  NewControi,  are  referred  to  as 
extended  controls.  Functionally,  extended  controls  do  not  differ  from  controls  created 
by  NewControi.  In  fact,  extended  control  records  will  work  with  all  Control  Manager  tool 
calls.  However,  the  control  record  for  an  extended  control  contains  more  data  than  the 
old-style  record.  In  addition,  many  new  Control  Manager  calls  and  features  are  valid  only 
for  extended  controls.  Note  that  any  control  created  by  NewControi2  is  an  extended 
control,  not  just  the  new  control  types.  For  complete  information  on  the  format  and 
content  of  extended  control  records,  see  "New  Control  Manager  templates  and  records" 
later  in  this  chapter. 

You  may  directly  call  NewControi2  or  you  may  invoke  it  indirectly  by  calling 

Newwindow2.  See  Chapter 45,  "Resource  Manager,"  and 

Chapter  52,  "Window  Manager  Update,"  for  details  on  new  window  calls. 

The  following  sections  discuss  each  type  of  control  supported  by  the  Control  Manager. 
For  the  original  controls,  these  sections  address  new  features  provided  by  the  Control 
Manager.  For  new  control  types,  these  sections  introduce  you  to  the  functionality  now 
provided. 

Simple  button  control 

Simple  button  controls  created  with  the  NewControi 2  tool  call  can  support  keystroke 
equivalents,  which  allow  the  user  to  activate  the  button  by  pressing  an  assigned  key  on  the 
keyboard.  See  "Keystroke  processing"  eariier  in  this  chapter  for  details. 

Check  box  control 

Check  box  controls  created  widi  the  NewControi2  tool  call  can  support  keysttoke 
equivalents,  which  allow  the  user  to  activate  the  box  by  pressing  an  assigned  key  on  the 
keyboard.  See  "Keystroke  processing"  eariier  in  this  chapter  for  details. 

Icon  button  control 

This  new  type  of  control  can  display  an  icon  as  well  as  text  in  a  defined  window.  You 
specify  the  boundary  rectangle  for  the  window  and  a  reference  to  the  icon  when  you 
create  the  control  (see  Chapter  17,  "QuickDraw  II  Auxiliary,"  in  Volume  2  of  the  Toolbox 
Reference  for  information  about  icons).  You  can  create  icon  button  controls  only  with  the 
NewControi 2  tOOl  call. 
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Icon  button  controls  operate  much  like  simple  button  controls.  Note,  however,  that  with 
icon  controls,  the  control  rectangle  is  inset  slightly  from  its  specified  coordinates  before 
the  button  is  drawn.  As  a  result,  outlined  round  buttons  stay  completely  within  the 
specified  control  rectangle  (this  is  not  the  case  for  an  outlined  round  simple  button 
control).  Icon  button  controls  support  keyboard  equivalents  (see  "Keystroke  processing" 
earlier  in  this  chapter  for  details). 

The  icon  is  drawn  each  time  the  control  is  drawn.  The  icon  and  text  are  centered  in  the 
specified  control  rectangle.  If  the  control  has  no  text,  the  icon  is  still  centered.  The  icon  is 
not  clipped  to  the  control  rectangle.  If  the  icon  is  larger  than  the  specified  control 
rectangle,  then  when  you  erase  the  control,  that  portion  of  the  icon  that  lay  outside  the 
rectangle  will  not  be  erased. 

Note  that  icon  controls  require  the  QuickDraw  II  Auxiliary  and  Resource  Manager  tool 
sets.  Note  as  well  that  the  control  definition  procedure  for  icon  buttons  is  kept  in  the 
system  resources  file. 

LineEdit  control 

This  new  control  type  lets  your  application  manage  single-line,  editable  items  in  a  window. 
You  specify  the  boundary  rectangle  for  the  text,  the  maximum  number  of  characters 
allowed,  and  an  initial  value  for  the  displayed  text  siring  when  you  create  the  control  with 
the  NewControi2  tool  call.  The  text  is  updated  each  time  the  control  is  drawn.  LineEdit 
controls  also  support  password  fields,  which  do  not  echo  the  characters  entered  by  the 
user.  Rather,  the  control  echoes  each  typed  charaaer  as  an  asterisk. 

LineEdit  controls  respond  to  both  mouse  and  keyboard  events.  If  your  application  uses 
TaskMaster,  the  system  will  handle  most  events  automatically.  To  take  full  advantage  of 

TaskMaSter,  set  the  tmContentControls,  tinControlKey,  and  tmldleEvents  flags 

in  the  taskMask  field  of  the  task  record  to  1  (see 

Chapter  52,  "Window  Manager  Update,"  for  information  about  the  new  features  in 
TaskMaster). 

If  your  application  does  not  use  TaskMaster,  when  the  user  presses  the  mouse  button  in  a 
LineEdit  control  your  application  must  call  xrackcontroi  to  track  the  mouse  and 
perform  appropriate  text  selection.  TaskMaster  will  do  this  automatically  if  you  have  set 
the  tmContentControls  flag  to  1  in  the  taskMask  field  of  the  task  record. 
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Without  TaskMaster,  your  application  sends  keyboard  events  to  LineEdit  controls  using 
the  SendEventToCti  tool  call  (see  "New  Control  Manager  calls"  later  in  this  chapter). 
First,  your  code  must  check  for  menu  key  equivalents.  If  none  are  found,  then  issue  the 
SendEventToCti  call,  setting  targetoniyFiag  to  FALSE  (all  controls  that  want 
events  are  searched),  windowPtr  to  NIL  (find  the  top  window),  and 
extendedTaskRecPtr  to  refer  to  the  task  record  containing  the  keystroke 
information.  Again,  TaskMaster  will  do  all  this  for  you  if  you  have  set  the  tmControiKey 
flag  to  1  in  the  taskMask  field. 

To  keep  the  caret  flashing,  your  application  must  send  idle  events  to  the  LineEdit  control. 
In  order  to  do  this,  issue  a  SendEventToCti  call,  setting  targetoniyFiag  to  TRUE 
(send  event  only  to  target  control),  windowPtr  to  NIL  (use  top  window),  and 
extendedTaskRecPtr  to  refer  to  the  task  record  containing  the  event  information. 
TaskMaster  will  do  this  for  you  if  you  have  set  the  tmidieEvents  flag  to  1  in  the 
taskMask  field. 

The  LineEdit  tool  set  performs  line  editing  in  LineEdit  controls.  If  you  want  to  issue 
LineEdit  tool  calls  directly  from  your  program,  retrieve  the  LineEdit  record  handle  from 
the  ctiData  field  of  the  control  record  for  the  LineEdit  control. 

List  control 

This  new  control  type  allows  your  program  to  display  lists  from  which  the  user  may  select 
one  or  more  items.  You  have  the  benefit  of  full  List  Manager  functionality,  with  respect  to 
such  features  as  selection  window  scrolling  and  item  selection  (single  item,  arbitrary 
items,  or  ranges).  You  specify  the  parameters  for  the  list  as  well  as  the  initial  conditions 
for  its  display  when  you  define  the  control.  The  Control  Manager  and  the  List  Manager 
take  care  of  the  rest.  You  can  create  list  controls  only  with  the  NewControi2  tool  call. 

List  controls  use  the  List  Manager  tool  set.  In  order  to  understand  how  to  use  this  control 
in  your  application,  see  Chapter  11,  "List  Manager,"  in  Volume  1  of  the  Toolbox  Reference. 

Picture  control 

This  new  control  type  displays  a  QuickDraw  picture  in  a  specified  window.  You  specify 
the  boundary  rectangle  for  the  control  and  a  reference  to  the  picture  when  you  create  the 
control.  The  picture  is  drawn  each  time  the  control  is  drawn.  You  can  create  picture 
controls  only  with  the  NewControi2  tool  call. 
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Note  that  when  the  picture  is  drawn,  the  boundary  rectangle  for  the  control  is  used  as  the 
picture  destination  rectangle  (see  Chapter  17,  "QuickDraw  II  Auxiliary,"  in  Volume  2  of 
the  Toolbox  Reference  for  details  about  picture  drawing).  As  a  consequence,  the  picture 
may  be  scaled  at  draw  time  if  the  original  picture  frame  does  not  have  the  same 
dimensions  as  the  control  rectangle.  To  force  the  picture  to  be  displayed  at  its  original 
size,  and  thus  avoid  scaling,  set  the  lower-right  comer  of  the  control  rectangle  to  (0,0). 
The  Control  Manager  recognizes  this  value  at  control  initialization  time,  and  sets  the 
control  rectangle  to  be  the  same  size  as  the  picture  frame. 

In  general,  a  click  in  a  picture  control  is  ignored.  However,  the  Control  Manager  provides 
facilities  to  inform  your  application  if  the  user  dicks  in  the  control.  To  make  a  picture 
control  inactive,  set  the  ctiHiiite  field  to  $FF,  otherwise  the  control  is  active  and  may 
receive  user  events. 

Note  that  picture  controls  require  the  QuickDraw  II  Auxiliary  tool  set. 
Pop-up  control 

This  new  control  type  allows  you  to  define  and  support  pop-up  menus  inside  a  window. 
You  specify  the  boundary  rectangle  for  the  control,  along  with  a  reference  to  the  menu 
definition  when  you  create  the  control  with  the  NewControi2  tool  call.  The  menu  tide 
becomes  the  tide  of  the  control,  and  the  current  selection  for  the  control  is  defined  by  the 
initial  value. 

Pop-up  controls  respond  to  both  mouse  and  keyboard  events.  If  your  application  uses 
TaskMaster,  the  system  will  handle  most  events  automatically.  To  take  full  advantage  of 

TaskMaster,  set  the  tmContentControls  and  tmControlKey  flags  in  the  taskMask 
field  of  the  task  record  to  1  (see  Chapter  52,  "Window  Manager  Update,"  for  information 
about  the  new  features  in  TaskMaster). 

If  your  application  does  not  use  TaskMaster,  when  the  user  presses  die  mouse  button 
inside  a  Pop-up  control,  your  application  must  call  Trackcontroi  to  track  the  mouse 
and  present  the  pop-up  menu  to  the  user.  TaskMaster  will  do  this  for  you  if  you  have  set 
die  tmContentControls  flag  tO  1  in  the  taskMask  field. 

Without  TaskMaster,  your  program  sends  keyboard  events  to  pop-up  menu  controls  using 
the  SendEventToCtl  tool  call  (see  "New  Control  Manager  calls"  later  in  this  chapter). 
First,  check  for  menu  key  equivalents.  If  none  are  found,  tiien  issue  the 
SendEventToCtl  call,  setting  targetOnlyFlag  to  FALSE  (all  controls  diat  want 
events  are  searched),  windowptr  to  NIL  (find  the  top  window),  and 
extendedTaskRecPtr  to  refer  to  the  task  record  containing  the  keystroke 
information.  TaskMaster  will  do  all  this  for  you  if  you  have  set  the  tmControiKey  flag  to 
1  in  the  taskMask  field. 
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Note  that  the  Control  Manager  places  the  current  user  selection  value  into  ctivaiue.  If 
you  need  to  retrieve  the  user  selection  number,  you  may  do  so  from  this  field. 

Radio  button  control 

Radio  button  controls  created  with  the  NewControi2  tool  call  can  support  keystroke 
equivalents,  which  allow  the  user  to  choose  a  button  by  pressing  an  assigned  key  on  the 
keyboard.  See  "Keystroke  processing"  eariier  in  this  chapter  for  details. 

Scroll  bar  control 

Scroll  bar  controls  provide  no  new  features. 
Size  box  control 

You  can  now  set  up  size  box  controls  to  automatically  invoke  Growwindow  and 
sizewindow  if  you  Create  the  control  with  the  NewControi2  tool  call.  When  the  user 
drags  the  size  box,  if  the  f  CaiiwindowMgr  bit  in  the  flag  field  of  the  size  box  control 
template  is  set  to  1  (see  the  description  of  the  size  box  control  template  in  "New  Control 
Manager  templates  and  records"  later  in  this  chapter),  the  Control  Manager  will  call 
Growwindow  and  sizewindow  to  track  the  control  and  resize  the  window  rectangle.  If 
this  flag  is  set  to  0,  then  the  control  is  merely  highlighted. 

Static  text  control 

This  new  control  type  displays  uneditable  (hence,  "static")  text  in  a  specified  window. 
You  can  place  font,  style,  size,  and  color  changes  into  the  displayed  text,  affording  you 
great  freedom  to  create  a  distinctive  text  display.  In  addition,  static  sext  controls  can 
accommodate  text  substitution.  With  this  feature,  you  can  customize  the  displayed  text 
to  fit  run-time  circumstances.  You  can  create  static  text  controls  only  with  the 
NewControl2  tool  call. 

If  you  are  going  to  use  text  substitution  in  your  static  text,  your  application  must  set  up 
the  control  template  correctly  (set  f  SubstituteText  in  flag  to  1)  and  tell  the  system 
where  the  substitution  array  is  kept  (issue  the  setctiParamPtr  Control  Manager  tool 
call).  The  text  substitution  array  has  the  same  format  as  that  used  by  the  Aiertwindow 
call  (see  Chapter  52,  "Window  Manager  Update,"  for  information  about  Aiertwindow 
and  for  substitution  array  format  and  content). 
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In  general,  applications  ignore  clicks  in  static  text  controls.  However,  the  Control 
Manager  provides  facilities  to  inform  your  application  if  the  user  clicks  in  the  control.  To 
make  a  static  text  control  inactive,  set  the  ctiHiiite  field  to  $FF,  otherwise  the 
control  is  active  and  may  receive  user  events. 

Note  that  static  text  controls  require  the  LineEdit,  QuickDraw  II  Auxiliary,  and  Font 
Manager  tool  sets. 

TextEdit  control 

This  control  lets  the  user  create,  edit,  or  view  multiline  items  in  a  window.  You  specify  the 
boundary  rectangle  for  the  edit  window,  parameters  governing  the  amount  of  text  to  be 
entered,  and,  optionally,  some  initial  text  to  display.  The  TextEdit  conu^ol  does  the  rest. 
You  can  only  create  TextEdit  controls  with  the  NewControi2  tool  call. 

The  TextEdit  control  uses  the  TextEdit  tool  set.  TextEdit  is  a  new  tool  set,  and  is 
completely  described  in  Chapter  49,  "TextEdit,"  later  in  this  book.  You  should  familiarize 
yourself  with  the  material  in  that  chapter  before  using  this  control. 


New  control  definition  procedure  messages 

Previously,  control  definition  procedures  had  to  support  13  message  types  (see 
Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox  Reference  ht  a  discussion  of  the 
original  message  types).  When  you  create  custom  controls  with  new  control  records  (see 
"New  Control  Manager  templates  and  records"  later  in  this  chapter),  your  control  will  have 
to  support  some  additional  messages. 


Value 

Control  Message  Description 

13 

ctlHandleEvent 

Handle  a  keystroke  or  menu  selection 

14 

ctlChangeTarget 

Issued  when  control's  target  status  has 

changed 

15 

ctlChangeBounds 

Issued  when  control's  boundary 

rectangle  has  changed 

16 

ctlWindChangeSize 

Window  has  been  grown  or  zoomed 

17 

ctlHandleTab 

Control  has  been  tabbed  to 

18 

ctlNotifyMultiPart 

A  multipart  control  must  be  hidden, 

drawn,  or  shown 

19 

ctlWinStateChange 

Window  state  has  changed 
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In  addition,  the  initcti,  dragCnti,  and  recsize  messages  have  new  control  routine 
interfaces  when  used  with  extended  controls.  The  following  sections  discuss  each  new  or 
changed  message  in  detail. 

If  you  must  draw  when  handling  control  messages,  your  control  definition  procedure 
should  save  the  current  GrafPort  and  set  the  port  correctly  for  your  control  before 
drawing.  After  your  defProc  is  finished  drawing,  restore  the  previous  GrafPort.  Note  that 
saving  the  current  GrafPort  includes  saving  penstate,  all  pattern  and  color  information, 
and  all  regions  in  the  port  to  which  your  program  draws. 

To  maintain  compatibility  with  future  versions  of  the  Control  Manager,  control  definition 
procedures  should  always  retum  a  retValue  of  0  for  unrecognized  and  unsupported  control 
message  types.  In  addition,  if  you  use  custom  control  messages,  be  careful  to  assign  type 
values  greater  than  $8000  (decimal  32,767). 

Initialize  routine 

Previously,  ctlParam  contained  paraml  and param2ltom  Newcontroi.  If  you  create 
your  custom  control  with  NewControi,  these  input  parameters  are  the  same.  However,  if 
you  aeate  your  control  with  NewControi2  (see  "New  Control  Manager  calls"  later  in  this 
chapter),  then  ctlParam  contains  a  pointer  to  the  control  template  for  the  control. 

Drag  routine 

The  result  code  for  the  drag  routine  now  contains  additional  information  that  allows 
control  definition  procedures  to  abort  tracking.  Previously,  retValue  indicated  whether  or 
not  your  defProc  wanted  the  Control  Manager  to  do  the  dragging.  For  controls  created 
with  NewControi,  this  is  Still  the  case.  For  controls  created  with  NewControi2,  your 
defProc  uses  the  low-order  word  of  retValue  exactly  as  before  (zero  means  that  the 
Control  Manager  should  drag  the  control;  nonzero  means  your  control  definition 
procedure  handled  it).  Your  defProc  returns  the  part  code  of  the  control  in  the  high-order 
word  (see  Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for 
information  on  control  part  codes).  If  this  value  is  0,  then  the  Control  Manager  assumes 
that  the  user  aborted  the  drag  operation  and  performs  no  screen  updates. 

Record  size  routine 

Previously,  ctlParam  was  undefined  for  this  routine.  Now,  the  Control  Manager  sets 
CtlParam  to  0  for  controls  created  with  NewControi.  For  controls  created  with 
NewControi2,  CtlParam  contains  a  pointer  to  the  control  template. 
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Event  routine 

To  pass  information  for  all  events,  including  keystroke  or  mouse  events,  the  Control 
Manager  calls  the  control  definition  procedure  with  the  ctiHandieEvent  message.  Only 
controls  you  create  with  either  the  f  ctiwantsEvents  bit  or  the  f  ctiCanBeTarget 
bit  set  to  1  in  the  moreFiags  field  of  the  control  template  will  receive  this  message  (see 
"New  Control  Manager  templates  and  records"  later  in  this  chapter  for  detailed 
information  on  these  flags).  The  first  qualifying  control  in  the  control  list  gets  the  first 
opportunity  to  handle  the  event.  If  that  control  processes  the  event,  then  no  other 
controls  see  it  If,  however,  that  control  does  not  process  the  event,  the  Control  Manager 
passes  the  event  to  the  next  qualifying  event  in  the  list.  This  process  continues  until  a 
control  handles  the  event,  or  the  list  is  exhausted.  If  no  defProc  handles  the  event, 
TaskMaster  passes  the  event  to  the  application. 

Parameters 

Stack  before  call 


Prmous  contents 


Space 


alMessage 


ctlParam 


-theControlHandle- 


Stack  after  call 


Long— Space  for  result 

Word— CtiHandieEvent  message 

Long— Pointer  to  task  record  containing  event  information 

Long— Handle  to  control 
<— SP 


Prmous  contents 


retValue 


Long— $FFFFFFFF  if  control  took  the  event;  $0  if  control  did  not 
<— SP 
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Target  routine 

To  signal  a  change  in  the  control's  target  status  (the  control  is  now,  or  is  no  longer,  the 
target),  the  Control  Manager  calls  the  control  definition  procedure  with  the 
ctichangeTarget  message.  Note  that  this  message  is  sent  to  both  the  previous  target 
control  and  the  new  target  control.  Your  control  definition  procedure  can  distinguish 
which  control  is  the  new  target  by  examining  the  f  ctiTarget  bit  in  the  ctiMoreFiags 
field  of  the  control  record.  The  new  target  control  will  have  this  bit  set  to  1  in  its  control 
record.  The  previous  target  will  have  the  bit  set  to  0. 

In  response  to  the  ctichangeTarget  message,  some  control  definition  procedures  will 
change  the  appearance  of  their  control  on  the  saeen  or  perform  other  actions  as 
appropriate.  For  example,  LineEdit  and  TextEdit  controls  display  an  insertion  point  or  a 
text  selection  only  when  they  are  the  target. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ctlMessage 


ctlParam 


-theControlHandle- 


Long— Space  for  result 

Word— CtichangeTarget  message 

Long— Undefined 

Long— Handle  to  control 
<— SP 


Stack  after  call 


Previous  contents 


retValue 


Long— Undefined 


<— SP 
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Bounds  routine 

To  signal  to  the  control  that  its  boundary  rectangle  has  changed  the  Control  Manager  calls 
the  control  definition  procedure  with  the  ctichangeBounds  message.  In  response  to 
this  message,  your  control  definition  procedure  should  adjust  its  intemal  control  record 
variables  to  account  for  the  new  rectangle.  For  example,  any  subrectangles  defined  for  a 
control  may  need  to  change  whenever  the  boundary  rectangle  changes. 

♦  Note:  This  message  is  not  supported  by  control  definition  procedures  currently 
provided  by  Apple;  however,  you  should  handle  this  message  in  any  custom  controls 
you  create. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ctlMessage 


ctlParam 


-theControlHandle- 


Long— Space  for  result 

Word — CtichangeBounds  message 

Long— Undefined 

Long— Handle  to  control 
<— SP 


Stack  after  call 


Previous  contents 


retValue 


Long— Undefined 


<— SP 
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Window  sl2e  routine 

The  Control  Manager  calls  the  control  definition  procedure  with  the 
ctiwindchangesize  message  whenever  the  user  has  changed  the  size  of  the  control 
window.  In  response  to  this  message,  your  control  definition  procedure  should  do  what  is 
necessary  to  maintain  a  consistent  screen  presentation.  This  may  entail  resizing  multipart 
controls,  moving  size  boxes,  and  so  on. 

Parameters 

Stack  before  call 

Previous  contents 
Space 
ctlMessage 
ctlParam 

-theControlHandle- 


Stack  after  call 

Previous  contents 
retValue 


Long— Space  for  result 
Word— ctlWindChangeSize  message 
Long— Undefined 
Long— Handle  to  control 
<— SP 


Long— Undefined 
<— SP 
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Tab  routine 

Your  control  definition  procedure  receives  tiie  ctiHandiexab  message  when  the  user 
has  hit  the  Tab  key  while  another  control  is  the  target.  That  control's  defProc  will  have 
issued  the  MakeNextctiTarget  tool  call  before  sending  this  control  message.  As  a 
result,  your  control  is  the  target  control.  The  control  definition  procedure  should  perform 
the  appropriate  actions  in  response  to  becoming  the  target  as  a  result  of  a  Tab  keystroke, 
rather  than  a  mouse  dick.  For  example,  in  response  to  this  message,  LineEdit  and 
TextEdit  control  definition  procedures  select  all  the  text  in  the  control  in  preparation  for 
user  input 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ctlMessage 


ctlParam 


-theControlHandle- 


Long— Space  for  result 

Word— ctiHandieTab  message 

Long— Undefined 

Long— Handle  to  control 
<— SP 


Stack  after  call 


Previous  contents 


retValue 


Long— Undefined 


<— SP 
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Notify  multipart  routine 

The  Control  Manager  calls  the  control  definition  procedure  with  the 
ctiNotif  yMuitiPart  message  to  signal  that  a  multipart  control  needs  to  be  hidden, 
shown,  or  drawn.  This  message  is  relevant  only  to  multipart  controls,  which  may  not  fit 
within  their  boundary  rectangle  (for  example,  list  controls  consist  of  the  list  itself  and  a 
scroll  control,  which  is  separate).  That  is,  the  f  ctiisMuitiPart  bit  in  the  moreFiags 
field  of  the  control  template  must  be  set  to  1  for  a  control  to  receive  this  message.  In 
response  to  this  message,  your  defProc  must  do  what  is  needed  to  hide  or  show  the 
control  completely. 

The  low-order  word  of  ctlParam  tells  the  defProc  what  to  do. 

0  Hide  the  entire  control 

1  Erase  the  entire  control 

2  Show  the  entire  control 

3  Show  one  control 

Parameter 

Stack  before  call 

Prmous  contents 


ctlMessage 


CtlParam 


Space 


Long— Space  for  result 

Word— ctiNotif  yMuitiPart  message 

Long— High-word  is  undefined;  low-word  contains  option 


-theControlHandle- 


Long— Handle  to  control 


<— SP 


Stack  after  call 


Prmous  contents 


retValue 


Long— Undefined 


<— SP 
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Window  change  routine 

The  Control  Manager  calls  the  control  definition  procedure  with  the 
ctiwinstatechange  message  to  signal  that  the  state  of  the  window  containing  the 
control  has  changed.  For  example,  a  control  definition  procedure  will  receive  this  message 
whenever  the  control's  window  is  activated  or  deactivated.  At  this  time,  the  control 
definition  procedure  may  draw  dimmed  controls  in  windows  that  have  been  unhidden. 

The  low-order  word  of  the  ctlParam  parameter  contains  the  new  state  of  the  window: 

$0000   The  window  has  been  deactivated 
$0001    The  window  has  been  activated 

I  The  high-order  word  is  undefined. 

Parameter 

Stack  before  call 


Previous  contents 


Space 


ctlMessage 


CtlParam 


-theControlHandle- 


Long— Space  for  result 
Word — ctiwinstatechange  message 
I  Long— Low  word  contains  new  window  state;  high  word  undefined 

Long— Handle  to  control 
<— SP 


Stack  after  call 


Previous  contents 


retValue 


Long— Undefined 


<— SP 
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New  Control  Manager  calls 

The  following  sections  describe  new  Control  Manager  tool  calls,  in  alphabetical  order  by 
call  name. 


CallCtlDefProc  $2C10 

This  routine  calls  the  specified  control  with  the  specified  control  message  and  parameter. 
Set  the  param  parameter  to  0  if  the  control  definition  procedure  does  not  accept  an  input 
parameter  (see  "New  control  definition  procedure  messages"  earlier  in  this  chapter  for 
information  on  input  parameters  for  defProc  messages). 

Parameters 

Stack  before  call 


Previous  contents 


Space 


-  ctlHandle 


message 


param 


Stack  after  call 


Long— Space  for  result  from  control  definition  procedure 

Long— Handle  of  control  to  be  called 
Word— Control  message  to  send  to  control  definition  procedure 
Long— Parameter  to  pass  to  conu-ol  definition  procedure 
<— SP 


PretHous  contents 


Result 


Long— Result  value  from  control  definition  procedure 
<— SP 


Errors 


None 
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message,  param) ; 

Handle  ctlHandle; 
Word  message; 
Long  param; 
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CMLoadResource  $3210 

This  is  an  entry  point  to  the  internal  Control  Manager  routine  that  loads  resources.  You 
specify  the  resource  type  and  ID  of  the  resource  to  be  loaded.  See 
Chapter  45,  "Resource  Manager,"  for  more  information  on  resources. 

Any  errors  during  resource  load  result  in  system  death. 

A  Warning     Applications  must  never  issue  this  call,  a 

Paraflieters 

Stack  before  call 

Piwious  contents 

Space       -  Long— Space  for  result 

resourceType  Word— Type  of  resource  to  load 
resourcelD    -  Long— ID  of  resource  to  load 

<— SP 

Stack  after  call 


Pretnous  contents 


resourceHandle  - 


Long— Handle  of  loaded  resource 
<— SP 


Errors 
C 


None 


extern  pascal  Handle  CMLoadResource (resourceType, 
resourcelD) ; 

Word  resourceType; 
Long  resourcelD; 
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CMReleaseResource  $3310 

This  is  an  entry  point  to  the  interna!  Control  Manager  routine  that  releases  resources.  You 
specify  the  resource  type  and  E)  of  the  resource  to  be  released.  The  resource  is  released 
by  marking  it  purgeable.  See  Chapter  45,  "Resource  Manager,"  for  more  information  on 
resources. 

Any  errors  result  in  system  death. 


A  Warning     Applications  must  never  issue  this  call.  ▲ 


Parameters 


Stack  before  call 


Previous  contents 


resourcelD 


resourceType 


Word— Type  of  resource  to  release 
Long— ID  of  resource  to  release 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


None 


C 


extern  pascal  void  CMReleaseResource (resourceType, 


resourcelD) ; 


Word 


resourceType ; 
resourcelD; 


Long 
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FindTargetCtl  $2610 

Searches  the  control  list  for  the  active  window  and  returns  the  handle  of  the  target  control 
(the  control  that  is  currently  the  target  of  user  keystrokes).  FindTargetCtl  returns  the 
handle  of  the  first  control  that  has  the  f  ctiTarget  flag  set  to  1  in  the  ctiMoreFiags 
field  of  its  control  record.  If  no  target  control  is  found  or  an  error  occurs,  then  the  call 
returns  a  NIL  handle. 

This  call  will  only  return  a  handle  to  an  extended  control. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long— Space  for  result 


<— SP 


Stack  after  call 


Pretnous  contents 


Result 


Long— Handle  of  target  control  (if  found);  NIL  if  none  or  error 


<— SP 


Errors 


$1004 
$1005 
$1006 
$100C 


noSuperCtlError 
noCtlTargetError 
noWind  Err 


noCtlError 


No  controls  in  window 
No  extended  controls  in  window 
No  target  extended  control 
No  front  window 


C 


extern  pascal  Handle  FindTargetCtl () ; 
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GetCtlHandleFromID  $3010 

Retrieves  the  handle  to  the  control  record  for  a  control  with  a  specified  ctiiD  field  value. 
The  ctiiD  field  is  an  application-defined  tag  for  a  control.  Set  the  ctiiD  field  with  the 
setctiiD  tool  call;  read  the  contents  of  the  ctiiD  field  with  GetctiiD. 

If  an  error  occurs,  the  returned  handle  is  NIL. 

jlhis  call  is  valid  only  for  extended  controls. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


-  windowPtr 


ctllD 


Stack  after  call 


Long— Space  for  result 

Long— Pointer  to  window  for  control  list  search;  NIL=top  window 

Long— ID  value  for  desired  control 
<— SP 


Previous  contents 


ctlHandle  - 


Errors 


$1004 
$1005 
$1009 

$100C 


Long— Handle  for  specified  control 
<— SP 


noCtlError 

noSuperCtlError 

noSuchlDError 

noWind  Err 


No  controls  in  window 

No  extended  controls  in  window 

The  specified  ID  cannot  be 

found 

There  is  no  front  window 


extern  pascal  Long  GetCtlHandleFromID (windowPtr, 
ctllD) ; 


Pointer 
Long 


windowPtr; 
ctllD; 
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GetCtllD  $2A10 

Returns  the  ctiiD  field  from  the  control  record  of  a  specified  control.  The  ctiiD  field  is 
an  application-defined  tag  for  a  control.  Your  application  can  use  this  field  in  many  ways. 
For  example,  since  the  value  of  ctiiD  is  known  at  compile  time,  you  can  construa 
efficient  routing  code  for  handling  control  messages  for  many  different  controls. 

Use  the  setctiiD  Control  Manager  tool  call  to  set  the  cti id  field. 

If  the  specified  control  is  not  an  extended  control,  the  resulting  ID  is  undefined,  and  an 
error  is  returned. 

Parameters 

Stack  before  call 


Prmous  contents 


Space 


ctlHandle  - 


Long— Space  for  result 

Long— Handle  to  control 
<— SP 


Stack  after  call 


PreiHous  contents 


ctllD 


Errors 


$1004 
$1007 


Long — ctiiD  for  specified  control 
<— SP 


noCtlError 
notSuperCtlError 


No  controls  in  window 
Action  valid  only  for  extended 
controls 


extern  pascal  Long  GetCtllD (ctlHandle) ; 
Handle  ctlHandle; 
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GetCtlMoreFlags  $2E10 

Gets  the  contents  of  the  ctiMoreFiags  field  of  the  control  record  for  a  specified 
control.  The  ctiMoreFiags  field  contains  flags  governing  target  status,  event 
processing,  and  other  aspects  of  the  control. 

Use  the  setctiMoreFiags  Control  Manager  tool  call  to  set  the  ctiMoreFiags  field. 

If  the  specified  control  is  not  an  extended  control,  the  result  is  undefined,  and  an  error  is 
returned. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ctlHandle  - 


Stack  after  call 


Word— Space  for  result 
Long— Handle  to  control 
<— SP 


Previous  contents 


CtiMoreFiags 


Errors 


Word— CtiMoreFiags  for  specified  control 
<-SP 

$1004      noCtiError  No  controls  in  window 

$1007      notSuperCtiError      Action  valid  only  for  extended 

controls 

extern  pascal  Word  GetCtlMoreFlags (ctlHandle) ; 
Handle  ctlHandle; 
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GetCtlParamPtr  $3510 

Retrieves  the  pointer  to  the  current  text  substitution  array  for  the  Control  Manager.  This 
array  contains  the  information  used  for  text  substitution  in  static  text  controls  (see 
"Static  text  control"  elsewhere  in  this  chapter  for  details). 

Set  the  contents  of  this  field  with  the  SetctiParamPtr  Control  Manager  tool  call. 

♦   Note:  This  pointer  is  global  to  the  Control  Manager;  it  is  not  associated  with  a  specific 
control.  As  a  result,  desk  accessories  should  be  very  careful  when  using  this  feature  to 
save  and  restore  the  previous  contents  of  the  field. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


-   subArrayPtr  - 


Long— Pointer  to  text  substitution  array 


<— SP 


Errors 


None 


C 


extern  pascal  Pointer  GetCtlParamPtr () ; 
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InvalCtls  $3710 

This  call  invalidates  all  rectangles  for  all  controls  in  a  specified  window. 

Parameters 

Stack  before  call 


Previous  contents 


-    windowPtr  - 


Stack  after  call 


Long— Pointer  to  window  for  operation 
<— SP 


Previous  contents 


Errors 
C 


<— SP 
None 

extern  pascal  void  InvalCtls (windowPtr) 
Pointer  windowPtr; 
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MakeNextCtlTarget  $2710 

Makes  the  next  eligible  control  the  target  control.  This  routine  searches  the  control  list  of 
the  active  window  for  the  first  target  control  (f  ctiTarget  bit  on  in  the 
ctiMoreFiags  field  of  the  control  record).  It  then  clears  the  target  flag  for  this  control, 
and  searches  for  the  next  control  in  the  control  list  that  can  be  the  target 
(fctiCanBeTarget  bit  set  to  1  in  ctiMoreFiags),  and  makes  that  control  the  target. 
The  call  returns  the  handle  of  the  new  target  control. 

Both  affected  controls  (the  old  and  new  target)  will  receive  ctiChangeTarget 
messages  from  the  Control  Manager. 

If  an  error  occurs,  the  returned  handle  is  NIL. 

This  call  is  valid  only  for  extended  controls. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long— Space  for  result  (handle) 


<— SP 


Stack  after  call 


Previous  contents 


Result 


Long— Handle  of  new  target  control;  NIL  if  error 


<— SP 


Errors 


$1004 
$1005 
$100B 


noSuperCtlError  r 
noCtlToBeTargetError 


noCtlError 


No  controls  in  window 
No  extended  controls  in  window 


No  control  could  be  made  target 


C 


extern  pascal  Handle  MakeNextCtlTarget () ; 
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MakeThisCtlTarget  $2810 

This  routine  makes  the  specified  control  the  target.  You  specify  the  control  that  is  to 
become  the  target  control  by  passing  its  handle  to  this  routine.  This  call  will  work  for  both 
active  and  inactive  windows. 

Both  affected  controls  (the  old  and  new  target)  will  receive  ctichangeTarget 
messages  from  the  Control  Manager. 

I  This  call  is  valid  only  for  extended  controls. 
Parameters 
Stack  before  call 


PreiHous  contents 


-  ctlToBeTarget  - 


Long— Handle  to  control  to  be  made  target 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1007 


<— SP 
notSuperCtlError 


Action  valid  only  for  extended 
controls 

$1008      canNotBeTargetError  Specified  Control  cannot  be 

made  target 

extern  pascal  void  MakeThisCtlTarget (ctlToBeTarget)  ; 
Handle  ctlToBeTarget; 
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NewCoiitrol2  $3110 

Creates  one  or  more  new  controls.  You  specify  the  parameters  governing  those  controls  in 
control  templates  that  are  passed  to  NewControi2  (see  "New  Control  Manager 
templates  and  records"  later  in  this  chapter).  If  NewControi2  creates  a  single  control,  it 
returns  the  handle  to  that  control  in  Result.  If  NewControi2  creates  two  or  more 
controls,  it  returns  0.  For  sample  code  showing  how  to  use  the  NewControi2  tool  call,  see 
"Control  Manager  code  example"  later  in  this  chapter. 

All  controls  created  by  NewControi2  have  new  style  control  records  and  are  extended 
controls. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


ownerPtr 


referenceDesc 


reference 


Long— Space  for  result 

Long— Pointer  to  window  for  control(s) 
Word— Describes  contents  of  reference 
Long— Reference  of  a  type  defined  by  referenceDesc 
<— SP 


Stack  after  call 


Previous  contents 


Result 


Errors 
C 


None 


Long— Control  handle  (if  single  control  created)  or  0 
<— SP 


extern  pascal  Handle  NewControl2 (ownerPtr, 
referenceDesc,  reference) ; 

Pointer  ownerPtr; 
Word  referenceDesc; 
Long  reference; 


Chapter  28  Control  Manager  Update  28-33 


Apple  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


referenceDesc       Defines  the  contents  and  type  of  item  referenced  by  reference. 
Possible  values  for  referenceDesc  are: 

singiePtr  0      reference  is  a  pointer  to  a  single  item 

template 

singieHandie         1      reference  is  a  handle  for  a  single  item 

template 

singieResource      2      reference  is  a  resource  ID  of  a  single 

item  template 

ptrToPtr  3      »e/e;ience  is  a  pointer  to  a  list  of 

pointers  to  item  templates 
ptrToHandie  4      reference  is  a  pointer  to  a  list  of  handles 

for  item  templates 
ptrToResource       5      reference  is  a  pointer  to  a  list  of 

resource  IDs  of  item  templates 
handieToPtr  6      reference  is  a  handle  to  a  list  of  pointers 

to  item  templates 
handieToHandie      7      reference  is  a  handle  to  a  list  of  handles 

for  item  templates 
handieToResource  8      re/erence  is  a  handle  to  a  list  of  resource 

IDs  of  item  templates 
resourceToResource      9        reference  is  a  resource  ID  of  a 

list  of  resource  IDs  of  item  templates 

If  reference  defines  a  list,  that  list  is  a  contiguous  array  of  template 
references  (pointers,  handles,  or  resource  IDs),  terminated  with  a 
^aJLL  entry. 
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NotifyCtls  $2D10 

Calls  the  control  definition  procedures  for  extended  controls  in  a  specified  window, 
sending  a  specified  control  message  and  parameter.  You  determine  which  controls  are  to 
be  called  by  setting  up  the  mask  field.  This  routine  compares  the  value  of  mask  with  that 
of  the  ctiMoreFiags  field  of  the  control  record  for  each  control  in  the  window.  If  any 
of  the  bits  you  have  specified  in  maskzK  set  to  1  in  ctiMoreFiags,  the  control  is  sent 
the  message  you  have  specified  (mask  is  bitwise  ANDed  with  ctiMoreFiags;  a  nonzero 
result  yields  a  call  to  the  control). 

Set  the  param  parameter  to  0  if  the  control  definition  procedure  does  not  accept  an  input 
parameter  (see  "New  control  definition  procedure  messages"  eariier  in  this  chapter  for 
information  on  input  parameters  for  defProc  messages). 

Parameters 

Stack  before  call 

Prmous  contents 


mask 


Word— Bit  mask  to  be  compared  with  ctiMoreFiags 
Word— Control  message  to  send  to  control  definition  procedures 
Long— Parameter  to  pass  to  control  definition  procedures 


message 


param 


window 


Long— GrafPort  of  window  whose  control  list  is  to  be  searched 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


None 


C 


extern  pascal  void  NotifyCtls (mask,  message,  param, 
window) ; 


Word 


mask,  message; 
param,  window; 


Long 
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SendEventToCtl  $2910 

Passes  a  specified  extended  task  record  (which  must  comply  with  the  new  format  defined 
in  Chapter  52,  "Window  Manager  Update,"  in  this  booic)  to  the  appropriate  control  or 
controls.  This  call  returns  a  Boolean  indicating  whether  the  event  was  fielded  by  a  control, 
and  returns  the  handle  of  the  control  that  serviced  the  event  in  taskData2  of  the  task 
record  for  the  event. 

The  targetOnlyFlag  parameter  governs  the  way  the  Control  Manager  searches  for  a  control 
to  field  the  event.  If  targetOnlyFlag  is  set  to  TRUE,  sendEventToCti  sends  the  event  to 
the  target  control.  If  there  is  no  target  control.  Result  is  FALSE  and  taskData2  is 
undefined. 

If  targetOnlyFlag  is  set  to  FALSE,  sendEventTocti  conducts  a  two-part  search  for  a 
control  to  field  the  event.  First,  Control  Manager  looks  for  non-edit  field  controls  that 
want  keystrokes  (for  example,  buttons  with  keystroke  equivalents).  The  Control  Manager 
tries  to  send  the  event  to  each  such  control  (with  the  ctiHandieEvent  control 
message).  If  no  control  accepts  the  event,  the  Control  Manager  looks  for  an  edit  field 
control  (LineEdit  or  TextEdit)  that  can  become  the  target.  If  no  control  accepts  the 
event  and  there  is  no  target,  Result  is  FALSE  and  taskData2  is  undefined.  Otherwise, 
Result  is  TRUE  and  taskData2  contains  the  handle  of  the  accepting  control. 

This  call  is  valid  only  for  extended  controls. 


♦  Note:  IS  a  control  can  be  made  the  target  (f  ctiCanBeiarget  is  set  to  1  in 
ctiMoreFiags  of  its  contTol  record),  then  the  Control  Manager  will  send  it  events 
regardless  of  the  setting  of  the  f  ctiwantsEvents  bit. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


targetOnlyFlag 


-    windowPtr  - 


-  eTaskRecPtr 


Word— Space  for  result  Boolean 

Word— (Boolean)  TRUE-send  to  target  only;  FALSE-all  controls 
Long— Pointer  to  window  to  search;  NIL  for  top  window 

Long— Pointer  to  extended  task  record  for  event 
<— SP 
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Stack  after  call 


Pretnous  contents 


Result 


Errors 


$1005 
$100C 


Word— (Boolean)  TRUE  if  event  accepted;  otherwise  FALSE 
<— SP 


noSuperCtlError 
noWind  Err 


No  extended  controls  in  window 
There  is  no  front  window 


extern  pascal  Boolean  SendEventToCtl (targetOnlyFlag, 
windowPtr,  eTaskRecPtr) ; 

Word  targetOnlyFlag; 
Pointer      windowPtr,  eTaskRecPtr; 
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SetCtllD  $2B10 

Sets  the  ctiiD  field  in  the  control  record  of  a  specified  control.  The  ctiiD  field  is  an 
application-defined  tag  for  a  control.  Your  application  can  use  this  field  in  many  ways. 
For  example,  since  the  value  of  ctiiD  is  knowable  at  compile  time,  you  can  construct 
efficient  routing  code  for  handling  control  messages  for  many  different  controls. 

Retrieve  the  ctiiD  field  for  a  control  with  the  GetctiiD  Control  Manager  call. 
If  the  specified  control  is  not  an  extended  control,  an  error  is  returned. 
Parameters 
Stack  before  call 


PreiHous  contents 


newID 


ctlHandle 


Long— New  ctiiD  value  for  the  control 

Long— Handle  to  control 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1004 
$1007 


<— SP 

noCtlError 
notSuperCtlError 


No  controls  in  window 
Action  valid  only  for  extended 
controls 


extern  pascal  void  SetCtllD (newID,  ctlHandle); 


Long 
Handle 


newID; 
CtlHandle; 
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SetCtlMoreFlags  $2F10 

Sets  the  contents  of  the  ctiMoreFiags  field  of  the  control  record  for  a  specified 
control.  The  ctiMoreFiags  field  contains  flags  governing  target  status,  event 
processing,  and  other  aspects  of  the  control. 

Retrieve  the  ctiMoreFiags  field  for  a  control  with  the  GetctiMoreFiags  Control 
Manager  call. 

If  the  specified  control  is  not  an  extended  control,  an  error  is  returned. 

Parameters 

Stack  before  call 


Previous  contents 


newMoreFlags 


ctlHandle 


Word— New  ctiMoreFiags  value  for  the  control 
Long— Handle  to  control 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1004 
$1007 


<— SP 

noCtlError 
notSuperCtlError 


No  controls  in  window 
Action  valid  only  for  extended 
controls 


extern  pascal  void  SetCtlMoreFlags (newMoreFlags, 
CtlHandle) ; 


Word 
Handle 


newMoreFlags; 
CtlHandle; 
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SetCtlParamPtr  $3410 


Sets  the  pointer  to  the  current  text  substitution  array  for  the  Control  Manager.  This  array 
contains  the  information  used  for  text  substitution  in  static  text  controls  (see  "Static 
text  controls"  elsewhere  in  this  chapter). 

Retrieve  the  contents  of  this  field  with  the  GetctiParamPtr  Control  Manager  tool  call. 


♦   Note:  This  pointer  is  global  to  the  Control  Manager;  it  is  not  associated  with  a 
specific  control.  As  a  result,  desk  accessories  should  be  very  careful  when  using  this 
feature  to  save  and  restore  the  previous  contents  of  the  field. 


Parameters 

Stack  before  call 


Previous  contents 


-   subArrayPtr  - 


Long— New  pointer  to  text  substitution  array 
<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  SetCtlParamPtr (subArrayPtr) ; 
Pointer  subArrayPointer; 
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Control  Manager  error  codes 


Value  Name  Definition 


$1001  wmNotstartedUp  Window  Manager  not  initialized 

$1002  cmNotinitiaiized  Control  Manager  not  initialized 

$1003  noCtiinList  Control  not  in  window  list 

$1004  noCtiError  No  controls  in  window 

$1005  noSuperCtiError  No  extended  controls  in  window 

$1006  noCtiTargetError  No  target  extended  control. 

$1007  notSuperctiError  Action  valid  only  for  extended  controls 

$1008  canNotBeTargetError  Specified  control  cannot  be  made 

target 

$1009  noSuchiDError  The  Specified  ID  cannot  be  found 

$100A  tooFewParmsError  Too  few  parameters  specified 

$100B  noCtiToBeTargetError  No  control  could  be  made  target 

$100C  nowind  Err  There  is  no  front  window 
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New  Control  Manager  templates  and  records 

This  section  describes  the  format  and  content  of  all  Control  Manager  control  templates 
and  records.  In  addition,  "Control  Manager  code  example"  shows  how  to  use  control 
templates  with  the  NewControi2  tool  call. 


NewControl2  input  templates 

Each  type  of  control  has  its  own  control  template,  corresponding  to  the  control  record 
definition  for  the  control  type.  The  item  template  is  an  extensible  mechanism  for  defining 
new  controls.  Rather  than  placing  all  the  control  parameters  on  the  stack  at  run  time,  the 
template  holds  these  parameters  in  a  standard  format  that  can  be  defined  at  compile 
time.  Furthermore,  the  templates  can  be  created  as  a  resource,  simplifying  program 
development  and  maintenance,  reducing  code  size,  and  reducing  fbced  memory  usage. 
Your  program  can  pass  more  than  one  input  template  to  NewControi2  at  a  time. 

All  control  templates  have  the  same  seven-field  header.  Some  templates  have  additional 
fields  that  further  define  the  control.  In  order  to  provide  extensible  support  for  variable 
length  templates,  one  of  the  header  fields  is  a  parameter  count.  The  value  of  the 
parameter  count  field  tells  the  Control  Manager  how  many  parameters  to  use,  which  allows 
for  optional  template  fields. 

The  following  sections  define  the  item  templates  for  each  control  type.  Field  names 
marked  with  an  asterisk  (*)  represent  optional  fields. 
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Control  template  standard  header 

Each  control  template  contains  the  standard  header,  which  consists  of  seven  fields. 
Following  that  header,  some  templates  have  additional  fields,  which  further  define  the 
control  to  be  created.  The  format  and  content  of  the  standard  template  header  is  shown 
in  Figure  28-1. 

Custom  control  definition  procedures  establish  their  own  item  template  layout.  The  only 
restriction  placed  on  these  templates  is  that  the  standard  header  be  present  and  well 
formed.  Custom  data  for  the  control  procedure  may  follow  the  standard  header. 


■   Figure  28-1     Control  template  standard  header 


$00 

—           pCount  — 

Word 

$02 

-                ID  — 

Long 

$06 

rect 

Rectangle 

$0E 

—           procRef  — 

Long 

$12 

flag 

Word 

$14 

—         moreFlags  — 

Word 

$16 

—            re f Con  — 

Long 

pCount  Count  of  parameters  in  the  item  template,  not  including  the  pCount 

field.  Minimum  value  is  6,  maximum  value  varies  depending  upon  the 
type  of  control  template. 
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ID  Sets  the  ctiiD  field  of  the  control  record  for  the  new  control.  The 

ctiiD  field  may  be  used  by  the  application  to  provide  a 
straightforward  mechanism  for  keeping  track  of  controls.  The  control 
E)  is  a  value  assigned  by  your  application,  which  the  control  "carries 
around"  for  your  convenience.  Your  application  can  use  the  ID,  which 
has  a  known  value,  to  identify  a  particular  control. 

rect  Sets  the  ctiRect  field  of  the  control  record  for  the  new  control. 

Defines  the  boundary  rectangle  for  the  control. 

procRef  Sets  the  ctiProc  field  of  the  control  record  for  the  new  control.  This 

field  contains  a  reference  to  the  control  definition  procedure  for  the 
control.  The  value  of  this  field  is  either  a  pointer  to  a  control 
definition  procedure,  or  the  ID  of  a  standard  routine.  The  standard 
values  are: 


simpleButtonControl 

$80000000 

Simple  button 

checkControl 

$82000000 

Check  box 

iconButtonControl 

$07FF0001 

Icon  button 

editLineControl 

$83000000 

LineEdit 

listControl 

$89000000 

List 

pictureControl 

$80000000 

Picture 

popUpControl 

$87000000 

Pop-up 

radioControl 

$84000000 

Radio  control 

scrollBarControl 

$86000000 

Scroll  bar 

growControl 

$88000000 

Size  box 

statTextControl 

$81000000 

Static  Text 

editTextControl 

$85000000 

TextEdit 
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flag  A  word  used  to  set  both  ctiHiiite  and  ctiFiag  in  the  control 

record  for  the  new  control.  Since  this  is  a  word,  the  bytes  for 
ctiHiiite  and  ctiFiag  are  reversed,  The  high-order  byte  of  flag 
contains  ctiHiiite,  while  the  low-order  byte  contains  ctiFiag. 
The  bits  in  flag  are  mapped  as  follows: 

Highlight  bits  8-15  Indicates  highlighting  style: 

0        Control  active,  no  highlighted 
parts 

1-254  Part  code  of  highlighted  part 
255      Control  inactive 
Invisible  bit  7       Governs  visibility  of  control: 

0  -  Control  visible 

1  -  Control  invisible 

Variable  bits  0-6    Values  and  meaning  depends  upon 

control  type 
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moreFlags 


Used  to  set  the  ctiMoreFiags  field  of  the  control  record  for  the 
new  control. 

The  high-order  byte  is  used  by  the  Control  Manager  to  store  its  own 
control  information.  The  low-order  byte  is  used  by  the  control 
definition  procedure  to  define  reference  types. 

The  defined  Control  Manager  flags  are: 


fCtlTarget 


$8000 


fCtlCanBeTarget  $4000 
fCtlWantEvents  $2000 


fCtlProcRefNotPtr  $1000 


fCtlTellAboutSize  $0800 


fCtllsMultiPart  $0400 


If  set  to  1,  this  control  is  currently  the  target  of 
any  typing  or  editing  commands. 
If  set  to  1  then  this  control  can  be  made  the 
target  control. 

If  set  to  1  then  this  control  can  be  called  when 
events  are  passed  via  the  sendEventTocti 
Control  Manager  call.  Note  that,  if  the 
fCtlCanBeTarget  flag  is  set  to  1,  this  control 
will  receive  events  sent  to  it  regardless  of 
setting  of  this  flag. 

If  set  to  1,  then  Control  Manager  expects 
ctiProc  to  contain  the  ID  of  a  standard 
control  procedure.  If  set  to  0,  then  c tip  roc 
contains  a  pointer  to  the  custom  control 
procedure. 

If  set  to  1,  then  this  control  needs  to  be 
notified  when  the  size  of  the  owning  window 
has  changed.  This  flag  allows  custom  control 
procedures  to  resize  their  associated  control 
images  in  response  to  changes  in  window  size. 
If  set  to  1,  then  this  is  a  multipart  control.  This 
flag  allows  control  definition  procedures  to 
manage  multi-part  controls  (necessary  since  the 
Control  Manager  does  not  know  about  all  the 
parts  of  a  multi-part  control). 
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The  low-order  byte  uses  the  following  convention  to  describe 


references  to  color  tables  and  titles  (note,  though,  that  some  control 

templates  do  not  follow  this  convention): 

titlelsPtr 

$00 

Title  reference  is  by  pointer 

titlelsHandle 

$01 

Title  reference  is  by  handle 

titlelsResource 

$02 

Title  reference  is  by  resource  ID 

colorTablelsPtr 

$00 

Color  table  reference  is  by  pointer 

colorTablelsHandle 

$04 

Color  table  reference  is  by  handle 

colorTablelsResource 

$08 

Color  table  reference  is  by  resource  ID 

re  f  Con            Used  to  set  the  > 

otiRef  Con  field  of  the  control  record  for  the  new 

control.  Reserved  for  application  use. 
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Keystroke  equivalent  information 

Many  of  these  control  templates  allow  you  to  specify  keystroke  equivalent  information 
for  the  associated  controls.  Figure  28-2  shows  the  standard  format  for  that  keystroke 
information. 


■   Figure  28-2     Keystroke  equivalent  record  layout 

$00 1            keyl  I  Byte 

$01   key2   Byte 

^02  _     keyModifiers    -  Word 
_      keyCareBi  ts      -  Word 


keyl  This  is  the  ASCII  code  for  the  upper  or  lower  case  of  the  key 

equivalent. 

key2  This  is  the  ASCII  code  for  the  lower  or  upper  case  of  the  key 

equivalent  Taken  with  keyi,  this  field  completely  defines  the  values 
against  which  key  equivalents  will  be  tested.  If  only  a  single  key  code 
is  valid,  then  set  keyl  and  key2  to  the  same  value. 

keyModifiers   These  are  the  modifiers  that  must  be  set  to  1  in  order  for  the 

equivalence  test  to  pass.  The  format  of  this  flag  word  corresponds  to 
that  defined  for  the  event  record  in  Chapter  7,  "Event  Manager,"  in 
Volume  1  of  the  Toolbox  Reference.  Note  that  only  the  modifiers  in  the 
high-order  byte  are  used  here. 

keyCareBits     These  are  the  modifiers  that  must  match  for  the  equivalence  test  to 
pass.  The  format  for  this  word  corresponds  to  that  for 
keyModifiers.  This  word  allows  you  to  discriminate  between 
double-modified  keystrokes.  For  example,  if  you  want  Control-7  to 
be  an  equivalent,  but  not  Option-Control-7,  you  would  set  the 
controlKey  bit  in  keyModifiers  and  both  the  optionKey  and  the 
controlKeyhirs  in  keyCareBits  to  1.  If  you  want  Return  and  Enter 
to  be  treated  the  same,  the  keyPad  bit  should  be  set  to  0. 
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Simple  button  control  template 

Figure  28-3  shows  the  template  that  defines  a  simple  button  control. 


■   Figure  28-3     Item  template  for  simple  button  controls 


$00 

pCount 

Word— Parameter  count  for  template:  7, 8,  or  9 

$02 

ID 

Long — ^Application-assigned  control  ID 

$06 

rect 

Rectangle — Boundary  reaangle  for  control 

$0E 

procRef 

Long— simpleButtonControl  =$80000000 

$12 

flag 

Word— Highlight  and  control  flags  for  control 

$14 

moreFlags 

Word— Additional  control  flags 

$16 

refCon 

Long— Application-defined  value 

$1A 

titleRef 

Long-Reference  to  title  for  button 

$1E 

*colorTableRef 

Long-Reference  to  color  table  for  control  (optional) 

$22 

*  IceyEqu  1  va  1  ent 

Block,  6  bytes— Keystroke  equivalent  data  (optional) 
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Defined  bits  for  flag  are 


I  Reserved 

ctllnvis 
Reserved 
Button  type 


bits  8-15     Must  be  set  to  0 
bit  7  l=invisible,  0=visible 

bits  2-6       Must  be  set  to  0 
bits  0-1       Describes  button  type; 

0  ■=  single-outlined  round-cornered  button 

1  -  bold-outlined  round-cornered  button 

2  »=  single-outlined  square-cornered  button 

3  =  single-outlined  square-cornered  drop- 
shadowed  button 


Defined  bits  formoreFiags  are 


fCtlTarget 
fCtlCanBeTarget 
fCtlWantsEvents 
fCtlProcNotPtr 

fCtlTellAboutSize 
Reserved 

Color  table  reference 


bit  15  Must  be  set  to  0 
bit  14  Must  be  set  to  0 
bit  13  Set  to  1  if  button  has  keystroke  equivalent 
bit  12  Must  be  set  to  1 
bit  11  Must  be  set  to  0 
bits  4-10     Must  be  set  to  0 

bits  2-3       Defines  type  of  reference  in  coiorxabieRef . 

See  Chapter  4,  "Control  Manager,"  in  Volume  1 
of  the  Toolbox  Reference  for  the  definition  of 
the  simple  button  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 
bits  0-1      Defmes  type  of  title  reference  in  titieRef : 

00  -  title  reference  is  pointer 

01  -  title  reference  is  handle 

10  -  title  reference  is  resource  ID 

11  -  invalid  value 

keyEquivaient  Keystroke  equivalent  information  stored  at  keyEquivaient  is 
formatted  as  shown  in  Figure  28-2. 


Title  reference 
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Check  box  control  template 

Figure  28-4  shows  the  template  that  defines  a  check  box  control. 


■   Figure  284     Control  template  for  check  box  controls 


$00 

pCount 

Word— Parameter  count  for  template:  8, 9,  or  10 

$02 

ID 

Long — ^Application-assigned  control  ID 

$06 

rect 

Rectangle— Boundary  rectangle  fa  control 

in? 

procRef 

Long— checkBoxControl  =$82000000 

$12 

flag 

Word— Highlight  and  control  flags  for  control 

$14 

moreFlags 

Wcffd— Additional  control  flags 

$16 

refCon 

Long— Application-defined  value 

$1A 

tltleRef 

Long— Reference  to  title  for  box 

$1E 

inltlalValue 

Word— Initial  box  setting:  0  for  clear,  1  for  checked 

$20 

•colorTableRef 

Long-Reference  to  color  table  for  control  (optional) 

$24 

•keyEquivalent 

Block,  6  bytes— Keystroke  equivalent  data  (optional) 

Defined  bits  for  flag  are 

Reserved  bits  8-15  Must  be  set  to  0 

ctiinvis  bit  7  l"invisible,  Divisible 

Reserved  bits  0-6  Must  be  set  to  0 
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Defined  bits  formoreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

Reserved 

Color  table  reference 


bit  15  Must  be  set  to  0 
bit  14         Must  be  set  to  0 

bit  13         Set  to  1  if  check  box  has  keystroke  equivalent 
bit  12         Must  be  set  to  1 
bit  11         Must  be  set  to  0 
bits  4-10     Must  be  set  to  0 

bits  2-3       Defines  type  of  reference  in  coiorTabieRef 
(see  Chapter  4,  "Control  Manager,"  in  Volume  1 
of  the  Toolbox  Reference  for  the  definition  of 
the  check  box  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  JD 

11  -  invalid  value 
bits  0-1       Defines  type  of  title  reference  in  titieRef : 

00  -  title  reference  is  pointer 

01  -  title  reference  is  handle 

10  -  title  reference  is  resource  ID 
11 -invalid  value 

keyEquivaient  Keystroke  equivalent  information  stored  at  keyEquivaient  is 
formatted  as  shown  in  Figure  28-2. 


Title  reference 
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Icon  button  control  template 

Figure  28-5  shows  the  template  that  defines  an  icon  button  control.  For  more  information 
about  icon  button  controls,  see  "Icon  button  control"  in  this  chapter. 


■   Figure  28-5     Control  template  for  icon  button  controls 


$00 

pCount 

Word— Parameter  count  for  template:  7, 8, 9, 10,  or  11 

$02 

ID 

Long — ^AppiiCdiion-aosigneu  conuoi  lu 

rect 

Rectangle— Boundary  rectangle  for  control 

JOE 

procRef 

Long— iconButtonControl  =$07FF0001 

$12 

flag 

Word— Highlight  and  contrd  flags  for  control 

$14 

moreFlags 

woro — AQQiuonai  coniroi  nags 

$16 

re f Con 

Long— Application-defined  value 

$1A 

IconRef 

Long— Reference  to  icon  for  cmtrol 

$1£ 

♦tltleRef 

Long— Reference  to  title  for  control  (optional) 

$22 

•colorTableRef 

Long— Reference  to  color  table  for  control  (optional) 

$26 

—       *dlsplayMode  — 

Word— Bit  flag  controlling  icon  appeararKe  (optional) 

$28 

*keyEqulvalent 

Block,  6  bytes — Key  equivalent  information  (optional) 
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Defined  bits  for  flag  are 

ctlHilite  bits  8-15 

ctllnvis  bit  7 

Reserved  bits  5-6 

showBorder  bit  2 

buttonType  bits  0-1 


Defined  bits  formoreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

f CtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

Reserved 

Icon  reference 


bit  15 
bit  14 
bit  13 
bit  12 
bit  11 
bits  6-10 
bits  4-5 


Color  table  reference 


bits  2-3 


Title  reference 


bits  0-1 


Sets  the  ctiHiiite  field  of  the  control  record 

l=invisible,  O^visible 

Must  be  set  to  0 

l=No  border,  0=Show  border 

Defines  button  type: 

00  -  single-outlined  round-cornered  button 

01  -  bold-outlined  round-cornered  button 

10  -  single-outlined  square-cornered  button 

11  -  single-outlined  square-cornered  and  drop- 
shadowed  button 


Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 

Defines  type  of  icon  reference  in  iconRef : 

00  -  icon  reference  is  pointer 

01  -  icon  reference  is  handle 

10  -  icon  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  reference  in  coiorTabieRef ; 
the  color  table  for  an  icon  button  is  the  same  as 
that  for  a  simple  button  (see 
Chapter  4,  "Control  Manager,"  in  Volume  1  of 
the  Toolbox  Reference  for  the  definition  of  the 
simple  button  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  title  reference  in  titieRef : 

00  -  title  reference  is  pointer 

01  -  tide  reference  is  handle 

10  -  title  reference  is  resource  ID 

11  -  invalid  value 
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titleRef 


displayMode 


Reference  to  the  title  string,  whicli  must  be  a  Pascal  string.  If  you  are 
not  using  a  title  but  are  specifying  other  optional  fields,  set 
moreFiags  bits  0  and  1  to  0,  and  set  this  field  to  zero. 

Passed  directly  totheorawicon  routine,  and  defines  the  display 
mode  for  the  icon.  The  field  is  defined  as  follows  (for  more 
information  on  icons,  see  Chapter  17,  "QuickDraw  II  Auxiliary,"  in 
Volume  2  of  the  Toolbox  Reference): 


Background  Color 
Foreground  Color 
Reserved 

of fLine 

openlcon 
selectedlcon 


bits  12-15 

bits  8-11 

bits  3-7 
bit  2 


bit  1 


bit  0 


Defines  the  background  color  to  apply  to  black 

part  of  black-and-white  icons. 

Defines  the  foreground  color  to  apply  to  white 

part  of  black-and-white  icons. 

Must  be  set  to  0 

1"AND  light-gray  pattern  to  image  being 
copied 

0-  Don't  AND  the  image 

1-  Copy  light-gray  pattern  instead  of  image 

0-  Don't  copy  light-gray  pattern 

1 -  Invert  image  before  copying 
0=Don't  invert  image 


Color  values  (both  foreground  and  background)  are  indexes  into  the 
current  color  table.  See  Chapter  l6,  "QuickDraw  II,"  in  Volume  2  of  the 
Toolbox  Reference  for  details  about  the  format  and  content  of  these 
color  tables. 

keyEquivaient  Keystroke  equivalent  information  stored  at  keyEquivaient  is 
formatted  as  shown  in  Figure  28-2. 
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LineEdit  control  template 

Figure  28-6  shows  the  template  that  defines  a  LineEdit  control.  For  more  information 
about  LineEdit  controls,  see  "LineEdit  control"  in  this  chapter. 


■   Figure  28-6     Control  template  for  LineEdit  controls 


$00 

pCount 

Word— Parameter  count  for  template  8 

$02 

ID 

Long-rApplicatioi-assigned  control  ID 

$06 

rect 

Rectangle— Boundary  rectangle  for  control 

$0E 

procRef 

Long— editLineControl  =$83000000 

$12 

flag 

Word— Highlight  and  control  flags  for  control 

$14 

inoreFlags 

Word— Additional  control  flags 

$16 

refCon 

Long— Appliation-defined  value 

$1A 

maxSlze 

Word— Maximum  length  of  input  line  (in  bytes) 

$1C 

defaultRef 

Long— Reference  to  default  text 

Defined  bits  for  flag  are 

Reserved  bits  8-15  Must  be  set  to  0 

ctiinvis  bit  7  1-invisible,  0-visible 

Reserved  bits  0-6  Must  be  set  to  0 
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Defined  bits  formoreFiags  are 


fCtlTarget 
fCtlCanBeTarget 
fCtlWantsEvents 
fCtlProcNotPtr 
fCtlTellAboutSize 

Reserved 
Text  reference 


maxSize 


bit  15  Must  be  set  too 
bit  14  Must  be  set  to  1 
bit  13  Must  be  set  to  1 
bit  12  Must  be  set  to  1 
bit  11  Must  be  set  to  0 
bits  2-10     Must  be  set  to  0 

bits  0-1       Defines  type  of  text  reference  in  de  f  a  u  1 1  Re  f 
GO  -  text  reference  is  pointer 
01  -  text  reference  is  handle 
10  -  text  reference  is  resource  ID 
11 -invalid  value 

Specifies  the  maximum  number  of  characters  allowed  in  the  LineEdit 
field.  Valid  values  lie  in  the  range  from  1  to  255. 

The  high-order  bit  indicates  whether  the  LineEdit  field  is  a  password 
field.  Password  fields  protect  user  input  by  echoing  asterisks,  rather 
than  the  actual  user  input.  If  this  bit  is  set  to  1,  then  the  LineEdit  field 
is  a  password  field. 


Note  that  LineEdit  controls  do  not  support  color  tables. 
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List  control  template 

Figure  28-7  shows  the  template  that  defines  a  list  control.  For  more  information  about  list 
controls,  see  "List  control"  in  this  chapter. 


■   Figure  28-7     Control  template  for  list  controls 


$00 

pCount 

Word— Parameter  count  for  template:  14  or  15 

$02 

ID 

Long— Application-assigned  control  H) 

$06 

rect 

Rectangle— Boundary  rectangle  for  control 

$0E 

procRef 

($0E)  Long— listControl  =$89000000 

$12 

flag 

Word— Highlight  and  control  flags  for  control 

$14 

moreFlags 

Word— Additional  ccmtrol  flags 

$16 

refcon 

Lcxig— Applicaiion-defmed  value 

$1A 

—         listSlze  — 

Word-Dumber  of  members  in  list 

$1C 

listVlew 

Word— dumber  of  members  visible  in  window 

$1E 

11 St Type 

Word— Type  of  list  entries,  selection  opticxis,  etc. 

$20 

liststart 

Word— First  visible  list  member 

$22 

llstDraw 

Lcxig— Pointer  to  member  drawing  routine 

$26 

llstMemHelght 

Word— Height  of  each  list  item  (in  pixels) 

$28 

llstMemSlze 

Word— Size  of  list  entry  (in  bytes) 

$2A 

listRef 

Long— Reference  to  list  of  member  records 

$2£ 

•colorTableRef 

Lcxig— Reference  to  color  table  for  control  (optional) 
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Defined  bits  for  flag  are 


Reserved 

ctllnvis 
Reserved 


bits  8-15     Must  be  set  to  0 
bit  7  1 -invisible,  0= visible 

bits  0-6       Must  be  set  to  0 


Defined  bits  for  moreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

f CtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

fCtllsMultiPart 

Reserved 

Color  table  reference 


List  reference 


bit  15  Must  be  set  to  0 
bit  14  Must  be  set  to  0 
bit  13  Must  be  set  to  0 
bit  12  Must  be  set  to  1 
bit  11  Must  be  set  to  0 
bit  10  Must  be  set  to  1 
bits  4-9       Must  be  set  to  0 

bits  2-3       Defines  type  of  reference  in  coiorTabieRef 
(the  color  table  for  a  List  control  is  described  in 
Chapter  11,  "List  Manager,"  in  Volume  1  of  the 
Toolbox  Reference) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

bits  0-1       Defines  type  of  reference  in  listRef  (the 

format  for  a  list  member  record  is  described  in 
Chapter  11,  "List  Manager,"  in  Volume  1  of  the 
Toolbox  Reference) 

00  -  list  reference  is  pointer 

01  -  list  reference  is  handle 

10  -  list  reference  is  resource  ID 

11  -  invalid  value 
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listType 


Valid  values  for  listType  are  as  follows: 


Reserved  bits3-15      Must  be  set  to  0. 

f  ListScroiiBar         bit  2  Allows  you  to  control  where  the  scroll  bar  for  the 

list  is  drawn: 

1  -  Scroll  bar  drawn  on  inside  of  boundary 
rectangle.  The  List  Manager  calculates  space 
needed,  adjusts  dimensions  of  boundary 
rectangle,  and  resets  this  flag. 

0  -  Scroll  bar  drawn  on  outside  of  boundary 
rectangle. 

bit  1  Controls  type  of  selection  options  available  to 

the  user: 

1  -  Only  single  selection  allowed 

0  -  Arbitrary  and  range  selection  allowed 
bit  0          Defines  the  type  of  strings  used  to  define  list 

items: 

1  -  C-strings  ($00-terminated) 
0  -  Pascal  strings 

For  details  on  the  remaining  custom  fields  in  this  template,  see  the  discussion  of  "List 
Controls  and  List  Records"  in  Chapter  11,  "List  Manager,"  of  Volume  1  of  the  Toolbox 
Reference. 


f ListSelect 


f ListString 
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Picture  control  template 

Figure  28-8  shows  the  template  that  defines  a  picture  control.  For  more  information  about 
picture  controls,  see  "Picture  control"  in  this  chapter. 


Figure  28-8     Control  template  for  picture  controls 


$00 

pCount 

Word— Parameter  count  for  template:  7 

$02 

ID 

Long— Application-assigned  control  ID 

$06 

rect 

Rectangle— Boundary  rectangle  for  control 

$0E 

procRef 

Long— pictureControl  =$80000000 

$12 

flag 

Word— Highlight  and  control  flags  for  control 

$14 

moreFlags 

Word— Additional  control  flags 

$16 

re f Con 

Long— Applicaticxi-defined  value 

$1A 

plctureRef 

Long— Reference  to  picture  for  control 

Defined  bits  for  flag  are 

ctlHilite  bits  &-15 


ctllnvis 

Reserved 


bit? 
bits  0-6 


Specifies  whether  the  control  wants  to  receive 

mouse  selection  events;  the  values  for 

CtlHilite  are  as  follows: 

0        Control  is  active 

255      Control  is  inactive 

1 -invisible,  0»visible 

Must  be  set  to  0 
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Defined  bits  for  moreFiags  are 


fCtlTarget  bit  15 

fCtlCanBeTarget  bit  14 

fCtlWantsEvents  bit  13 

fCtlProcNotPtr  bit  12 

fCtlTellAboutSize  bit  11 

Reserved  bits  2-10 

Picture  reference  bits  0-1 


Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 

Define  type  of  picture  reference  in 
pictureRef : 

00  -  invalid  value 

01  -  reference  is  handle 

10  -  reference  is  resource  ID 

11  -  invalid  value 


28^2    Apple  UGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Pop-up  control  template 

Figure  28-9  shows  the  template  that  defines  a  pop-up  control.  For  more  information  about 
pop-up  controls,  see  "Pop-up  control"  in  this  chapter. 


■   Figure  28-9     Control  template  for  pop-up  controls 


pCount 

Word— Parameter  couiu  for  template:  9  or  10 

$02 

ID 

Long— Application-assigned  control  ID 

rect 

Reaangie— Boundary  reaangle  for  control 

$0E 

procRef 

Long— popUpCont  ro  1 =$87000000 

$12 

flag 

Word— Highlight  and  control  flags  for  control 

$14 

moreFlags 

Word— Additional  control  flags 

$16 

ref Con 

Long— Application-defined  value 

$1A 

titleWidth 

Word— Width  in  pixels  of  title  string  area 

$1C 

menuRef 

Long— Reference  to  menu  definition 

$20 

InitlalValue 

Word— Item  ID  of  initial  item 

$22 

•colorTableRef 

Long— Reference  to  color  table  for  control  (optional) 

Chapter  28  Control  Manager  Update  28^3 


i4^fe  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Defined  bits  for  flag  are 


ctlHilite  bits  8-15 

ctllnvis  bit  7 

fType2PopUp  bit  6 

fDontHiliteTitle  bit  5 

fDontDrawTitle  bit  4 


fDontDrawResult  bit  3 


f  InWindowOnly  bit  2 


Specifies  whether  the  control  wants  to  receive 
mouse  selection  events;  the  values  for 
CtlHilite  are  as  follows: 

0  Control  is  active 
255      Control  is  inactive 
1 -invisible,  0-visible 

Tells  the  Control  Manager  whether  to  create  a 
pop-up  menu  with  white  space  for  scrolling  (see 
Chapter  37,  "Menu  Manager  Update,"  for  details 
on  Type  2  pop-up  menus); 

1  -  Draw  pop-up  with  white  space  (Type  2) 

0  -  Draw  normal  pop-up 

Controls  highlighting  of  the  control  title: 

1  -  Do  not  highlight  title  when  control  is  popped 
up 

0  -  Highlight  title 

Allows  you  to  prevent  the  title  from  being  drawn 
(note  that  you  must  supply  a  title  in  the  menu 
definition,  whether  or  not  it  will  be  displayed); 
if  titiewidth  is  defined  and  this  bit  is  set  to 
1,  then  the  entire  menu  is  offset  to  the  right  by 
titiewidth  pixels: 

1  -  Do  not  draw  the  title 

0  -  Draw  the  title 

Allows  you  to  control  whether  the  selection  is 
drawn  in  the  pop-up  rectangle: 

1  -  Do  not  draw  the  result  in  the  result  area  after 
a  selection 

0- Draw  the  result 

Controls  the  extent  to  which  the  pop-up  menu 
can  grow;  this  is  particularly  relevant  to  Type  2 
pop-ups  (see 

Chapter  37,  "Menu  Manager  Update,"  for  details 
on  Type  2  pop-up  menus): 
1  -  Keep  the  pop-up  in  the  current  window 
0  -  Allow  the  pop-up  to  grow  to  screen  size 
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fRightJustifyTitle    bit  1 


fRight JustifyResult  bit  0 


Defined  bits  formoreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 
fCtlTellAboutSize 

Reserved 

Color  table  reference 


bit  15 
bit  14 
bit  13 

bit  12 
bit  11 
bits  5-10 
bits  3-4 


fMenuDef IsText 


bit  2 


Controls  title  justification: 

1  -  Right  justify  the  title;  note  that  if  the  title  is 

right  justified,  then  the  control  rectangle  is 

adjusted  to  eliminate  unneeded  pixels  (see 

Figure  28-12),  the  value  for  titiewidth  is  also 

adjusted 

0  -  Left  justify  the  tide 
Controls  result  justification: 

1  -  Right  justify  the  selection 

0  -  Left  justify  the  selection  titiewidth 
pixels  from  the  left  of  the  pop-up  rectangle. 


Must  be  set  to  0 
Must  be  set  to  0 

Must  be  set  to  1  if  the  pop-up  has  any 
keystroke  equivalents  defined 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 

Defines  type  of  reference  in  coiorTabieRef 
(the  color  table  for  a  menu  is  described  in 
Chapter  13,  "Menu  Manager,"  in  Volume  1  of  the 
Toolbox  Reference) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  data  referred  to  by  menuRef : 
1  -  menuRef  is  a  pointer  to  a  text  stream  in 
NewMenu  format  (see 

Chapter  13,  "Menu  Manager,"  in  Volume  1  of  the 
Toolbox  Reference  for  details) 
0  -  menuRef  is  a  reference  to  a  Menu  Template 
(again,  see  Chapter  13,  "Menu  Manager,"  in 
Volume  1  of  the  Toolbox  Reference  for  details  on 
format  and  content  of  a  Menu  Template) 
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Menu  reference  bits  0-1 


Defines  type  of  menu  reference  in  menuRef  (if 
fMenuDef  isText  is  set  to  1,  then  these  bits 
are  ignored); 

00  -  menu  reference  is  pointer 

01  -  menu  reference  is  handle 

10  -  menu  reference  is  resource  E) 

11  -  invalid  value 


rect  Defines  the  boundary  rectangle  for  the  pop-up  and  its  tide,  before  the 

menu  has  been  "popped"  by  the  user.  The  Menu  Manager  will  calculate 
the  lower,  right  coordinates  of  the  rectangle  for  you,  if  you  specify 
those  coordinates  as  (0,0). 

initiaivaiue   The  initial  value  to  be  displayed  for  the  menu.  The  initial  value  is  the 
default  value  for  the  menu,  and  is  displayed  in  the  pop-up  rectangle  of 
"unpopped"  menus.  You  specify  an  item  by  its  YD,  that  is,  its  relative 
position  within  the  array  of  items  for  the  menu  (see 
Chapter  37,  "Menu  Manager  Update,"  for  information  on  the  layout 
and  content  of  the  pop-up  menu  template).  If  you  pass  an  invalid 
item  ID  then  no  item  is  displayed  in  the  p0j>up  rectangle. 

titiewidth      Provides  you  with  additional  control  over  placement  of  the  menu  on 
the  saeen.  The  titiewidth  field  defines  an  offset  from  the  left 
edge  of  the  control  (boundary)  rectangle  to  the  left  edge  of  the  pop- 
up rectangle  (see  Figure  28-11).  If  you  are  creating  a  series  of  pop-up 
menus  and  you  want  them  to  be  vertically  aligned,  you  can  do  this  by 
giving  all  menus  the  same  xl  coordinate  and  titiewidth  value.  You 
may  use  titiewidth  for  this  even  if  you  are  not  going  to  display  the 
tide  (f DontDrawTitle  flag  is  sct  to  1  in  flag).  If  you  set 
titiewidth  to  0,  then  the  Menu  Manager  determines  its  value  based 
upon  the  length  of  the  menu  tide,  and  die  pop-up  rectangle 
immediately  follows  die  tide  string.  If  the  actual  widdi  of  your  tide 
exceeds  die  value  of  titiewidth,  results  are  unpredictable. 

menuRef  Reference  to  menu  definition  (see  Chapter  13,  "Menu  Manager,"  in 

Volume  1  of  the  Toolbox  Reference  zaA 

Chapter  37,  "Menu  Manager  Update,"  in  diis  book  for  details  on  menu 
templates).  The  type  of  reference  contained  in  menuRef  is  defined 
by  the  menu  reference  bits  in  moreFiags. 
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u   Figure  28-10    "Unpopped"  pop-up  menu 

(Pop-up  rectangle) 

/ 


Baud  rate:  300 


■   Figure  28-11    "Popped"  pop-up  menu,  left-justified  title 
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m   Figure  28-12    "Popped"  pop-up  menu,  right-justified  title 
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Radio  button  control  template 

Figure  28-13  shows  the  template  that  defines  a  radio  button  control: 


■   Figure  28-13   Control  template  for  radio  button  controls 


$00 

pCount 

woro — rarameier  couni  lor  icmpidie:  o,  y,  or  lu 

$02 

ID 

Long — Application-assigned  control  ID 

$06 

rect 

Rectangle — ^Boundary  rectangle  fa  control 

$0E 

procRef 

Long— radioButtonControl  =$84000000 

$12 

flag 

Word— Highlight  and  control  flags  for  control 

$14 

moreFlags 

Word— Additional  control  flags 

$16 

re f Con 

Long— Application-defined  value 

$1A 

tltleRef 

Long— Reference  to  title  for  buttcai 

$1E 

initialValue 

Word— Initial  settiag:  0  for  dear,  1  for  set 

$20 

•colorTableRef 

Long— Reference  to  color  table  for  control  (optional) 

$24 

*keyEquivalent 

Block,  6  bytes— Keystroke  equivalent  data  (optional) 
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Defined  bits  for  flag  are 

Reserved  bits  8-15 

ctllnvis  bit  7 

Family  number  bits  0-6 


Must  be  set  to  0 
l=invisibie,  0=visible 

Family  numbers  define  associated  groups  of 
radio  buttons;  radio  buttons  in  the  same  family 
are  logically  linked,  that  is,  setting  one  radio 
button  in  a  family  clears  all  other  buttons  in  the 
same  family 


Defined  bits  formoreFiags  are  as  follows: 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

Reserved 

Color  table  reference 


bit  15  Must  be  set  to  0 
bit  14  Must  be  set  to  0 
bit  13  Set  to  1  if  button  has  keystroke  equivalent 
bit  12  Must  be  set  to  1 
bit  11  Must  be  set  too 
bits  4-10     Must  be  set  to  0 

bits  2-3       Defines  type  of  reference  in  coiorTabieRef 
(see  Chapter  4,  "Control  Manager,"  in  Volume  1 
of  the  Toolbox  Reference  for  the  definition  of 
the  radio  button  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 
10  -  color  table  reference  is  resource  ID 
11 -invalid  value 

bits  0-1       Defines  type  of  title  reference  in  titieRef : 

00  -  title  reference  is  pointer 

01  -  title  reference  is  handle 

10  -  title  reference  is  resource  E) 
11 -invalid  value 

keyEquivaient  Keystroke  equivalent  information  stored  at  keyEquivaient  is 
formatted  as  shown  in  Figure  28-2. 


Title  reference 
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Scroll  bar  control  template 

Figure  28-14  shows  the  template  that  defines  a  scroE  bar  control: 


■   Figure  28-14   Control  template  for  scroll  bar  controls 


$00 

pCount 

- 

Word— Parameter  count  for  template:  9  or  10 

$02 

- 

ID 

- 

Lone  ^AoDlication-assicned  control  ID 

$06 

rect 

Rectangle— Boundary  rectangle  for  control 

$0E 

procRef 

Long— scrollControl  =$86000000 

$12 

flag 

Word— Highlight  and  contrci  flags  for  control 

$14 

moreFlags 

Word— Additional  control  flags 

$16 

re f Con 

Long— Appliation-defined  value 

$1A 

maxSlze 

Wad— Initial  size  of  displayed  item 

$1C 

viewSize 

Word— Amount  of  item  initially  visible 

$1E 

inltialValue 

Wcffd— Initial  setting 

$20 

•colorTableRef 

Long— Reference  to  color  table  for  control  (optional) 

Chapter  28  Control  Manager  Update  28-71 


Apple  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Defined  bits  for  flag  are 


Reserved 

bits  8-15 

Must  be  set  to  0 

ctllnvis 

bit? 

1  "invisible,  0=visible 

Reserved 

bits  5-6 

Must  be  set  to  0 

horScroll 

bit  4 

1-horizontal  scroll  bar,  0"vertical  scroll  bar 

rightFlag 

bit  3 

l=bar  has  right  arrow,  0=bar  has  no  right  arrow 

leftFlag 

bit  2 

1-bar  has  left  arrow,  0=bar  has  no  left  arrow 

downFlag 

bit  1 

1-bar  has  down  arrow,  0-bar  has  no  down  arrow 

upFlag 

bitO 

l«bar  has  up  arrow,  0»bar  has  no  up  arrow 

Note  that  extraneous  flag  bits  are  ignored,  based  upon  state  of  horscroii  flag.  For 

example,  for  vertical  scroll  bars,  rightFlag  and  lef  tFiag  are  ignored. 

Defined  bits  for  moreFiags  are 

fCtlTarget 

bit  15 

Must  be  set  to  0 

fCtlCanBeTarget 

bit  14 

Must  be  set  to  0 

f CtlWantsEvents 

bit  13 

Must  be  set  to  0 

fCtlProcNotPtr 

bit  12 

Must  be  set  to  1 

fCtlTellAboutSize 

bit  11 

Must  be  set  to  0 

Reserved 

bits  4-10 

Must  be  set  to  0 

Color  table  reference 

bits  2-3 

Defines  type  of  reference  in  colorTableRef  (.see 

Chapter  4,  "Control  Manager,"  in  Volume  1  of 

the  Toolbox  Reference  and  "Clarifications"  earlier 

in  this  chapter  for  the  definition  of  the  scroll 

bar  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Reserved 

bits  0-1 

Must  be  set  to  0 
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Size  box  control  template 

Figure  28-15  shows  the  template  that  defines  a  size  box  control: 


Figure  28-15   Control  template  for  size  box  controls 


$00 

pCount 

Word— Parameter  coimt  for  template:  6  or  7 

$02 

ID 

Long— Application-assigned  control  ID 

$06 

$0E 

$12 
$14 
$16 

$20 


procRef 


:  Rectangle— Boundary  rectangle  for  control 
Long—  gr  owCont  ro  1  =$88000000 


flag 


moreriags  — 


re f Con 


—     •colorTableRef  — 


Word— Highlight  and  control  flags  for  control 
Word— Additional  control  flags 

Long— Application-defined  value 

Long— Reference  to  color  table  for  control  (optional) 


Defined  bits  for  flag  are 

Reserved  bits  &-15 

ctllnvis  bit  7 

Reserved  bits  1-6 

f  CallWindowMgr  bit  0 


Must  be  set  to  0 
1-invisible,  0=visible 
Must  be  set  to  0 

l-call  GrowWindow  and  SizeWindow  tO  track 
this  control 

0-just  highlight  control 
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Defined  bits  formoreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

Reserved 

Color  table  reference 


Reserved 


bit  15  Must  be  set  to  0 
bit  14  Must  be  set  to  0 
bit  13  Must  be  set  to  0 
bit  12  Must  be  set  to  1 
bit  11  Must  be  set  to  0 
bits  4-10     Must  be  set  to  0 

bits  2-3      Defines  type  of  reference  in  coiorTabieRef 
(see  "Error  Corrections"  earlier  in  this  chapter 
for  the  definition  of  the  size  box  color  table) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 
bits  0-1       Must  be  set  to  0 
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Static  text  control  template 

Figure  28-16  shows  the  template  that  defines  a  static  text  control.  For  more  information 
about  static  text  controls,  see  "Static  text  control"  in  this  chapter. 


■   Figure  28-16   Control  template  for  static  text  controls 


$00 

- 

pCount 

Word— Parameter  count  for  template:  7, 8,  or  9 

$02 

- 

ID 

- 

Long— Application-assigned  control  ID 

$06 

rect 

Rectangle— Boundary  rectangle  for  control 

$0E 

procRef 

Long— statTextControl  =$81000000 

$12 

flag 

Word— Highlight  and  control  flags  for  control 

$14 

moreFlags 

Word— Additional  control  flags 

$16 

re f Con 

Long— Application-defmed  value 

$1A 

textRef 

Long— Reference  to  text  for  control 

$1E 

•textSize 

Word— Text  size  field  (optional) 

$20 

*just 

Word— Initial  justificatton  for  text  (optional) 

Defined  bits  for  flag  are 

Reserved 

bits  8-15 

Must  be  set  to  0 

ctllnvis 

bit? 

1 -invisible,  0-visible 

Reserved 

bits  2-6 

Must  be  set  to  0 

f SubstituteText 

bit  1 

0=no  text  substitution  to  perform 

l=there  is  text  substitution  to  perform 

f SubTextType 

bitO 

0=C  strings 

l-^Pascal  strings 
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Defined  bits  formoreFiags  are 


fCtlTarget 
fCtlCanBeTarget 
f CtlWantsEvents 
fCtlProcNotPtr 
fCtlTellAboutSize 
Reserved 
Text  Reference 


textSize 


just 


bit  15  Must  be  set  to  0 
bit  14  Must  be  set  to  0 
bit  13  Must  be  set  to  0 
bit  12  Must  be  set  to  1 
bit  11  Must  be  set  to  0 
bits  2-10  Must  be  set  to  0 
bits  0-1       Defines  type  of  text  reference  in  textRef : 

00  -  text  reference  is  pointer 

01  -  text  reference  is  handle 

10  -  text  reference  is  resource  ID 

11  -  invalid  value 

The  size  of  the  referenced  text  in  characters,  but  only  if  the  text 
reference  in  textRef  is  a  pointer.  If  the  text  reference  is  either  a 
handle  or  a  resource  ID,  then  the  Control  Manager  can  extract  the 
length  from  the  handle. 

The  justification  word  is  passed  on  to  LETextBox2  (see 
Chapter  10,  "LineEdit  Tool  Set,"  in  Volume  1  of  the  Toolbox  Reference 
for  details  on  the  LETextBox2  tool  call),  and  is  used  to  set  the  initial 
justification  for  the  text  being  drawn.  Valid  values  for  just  are 


leftJustify  0 

centerJustify  1 

rightJustify  -1 

fullJustify  2 


Text  is  left  justified  in  the  display  window 
Text  is  centered  in  the  display  window 
Text  is  right  justified  in  the  display  window 
Text  is  fully  justified  (both  left  and  right)  in 
the  display  window 


Static  text  controls  do  not  support  color  tables.  In  order  to  display  text  of  different 
color,  you  must  embed  the  appropriate  commands  into  the  text  string  you  are  displaying. 
See  the  discussion  of  LETextBox2  in  Chapter  10,  "LineEdit  Tool  Set,"  in  Volume  1  of  the 
Toolbox  Reference  for  details  on  command  format  and  syntax. 
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TextEdit  control  template 

Figure  28-17  shows  the  template  that  defines  a  TextEdit  control.  For  more  information 
about  TextEdit  controls,  see  TextEdit  control"  in  this  chapter. 


Figure  28-17   Control  template  for  TextEdit  controls 


$00 

pCount 

Word— Parameter  count  for  template:  7  to  23 

J02 

ID 

Long— Application-assigned  control  ID 

$06 

rect 

Rectangle— Boundary  rectangle  for  control 

$0E 

procRef 

Long— editTextControl=$85000000 

$12 

flag 

Word— Highlight  and  control  flags  for  control 

$14 

moreFlags 

Word— Addiuonal  control  flags 

$16 

refCon 

Long— Application-defmed  value 

$1A 

textFlags 

Long— Specific  TextEdit  control  flags  (see  below) 

$1E 

•indentRect 

Rectangle— Defines  text  indentation  firom  control  rea  (optional) 

$26 

•vert  Bar 

Long— Handle  to  vertical  saoll  bar  for  control  (optional) 

$2A 

*vert Amount 

Wad— Vertical  saoll  amount,  in  pixels  (optional) 

$2C 

•horzBar 

Long— Reserved;  must  be  set  to  NIIL  (optional) 

$30 

•horzAinount 

Word— Reserved;  must  be  set  to  0  (optional) 

conlinued 
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continued 

$32 

•styleRef 

- 

Long — Reference  to  initial  style  information  for  text  (optional) 

♦textDescriptor 

Word — Defines  format  of  initial  text  and  textRef  (optional) 

$38 

•textRef 

Long— Reference  to  initial  text  for  edit  window  (optional) 

•textLength 

Long— Length  of  initial  text  (optional) 

$40 

*maxChars 

Long— Maximiun  numba  of  charaders  allowed  (optional) 

$44 

•maxLlnes 

T  nno  Rpv^rvf^*  mii^l  hf*  sf*t  to  0  Tootional) 

$48 

*maxCharsPerLlnes 

word— Acoervcuj  muoL  uc  ocl  lu  u  v.upuuiiiii/ 

$4A 

•maxHeight 

Word— Reserved;  must  be  set  to  0  (optional) 

$4C 

•oolorRef 

Long— Reference  to  TextEdit  color  table  (optional) 

$50 

♦drawMode 

Word— QuickDraw  II  text  mode  for  edit  wirxlow  (optional) 

$52 

*fHterProcPtr 

Long— Pointer  to  filter  routine  for  this  control  (optional) 

Defined  bits  for  flag  are 

Reserved  bits  8-15  Must  be  set  to  0 

ctiinvis  bit  7  1-invisible,  0-visible 

Reserved  bits  0-6  Must  be  set  to  0 
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Defined  bits  formoreFiags  are 


fCtlTarget 
fCtlCanBeTarget 
fCtlWantsEvents 
fCtlProcNotPtr 
f TellAboutSize 


fCtllsMultiPart 
Reserved 

Color  table  reference 


Style  reference 


bit  15 
bit  14 
bit  13 
bit  12 
bit  11 


bit  10 
bits  4-9 
bits  2-3 


bits  0-1 


Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  1 
Must  be  set  to  1 

If  set  to  1,  a  size  box  will  be  created  in  the 
lower-right  comer  of  the  window.  Whenever  the 
control  window  is  resized,  the  edit  text  will  be 
resized  and  redrawn. 
Must  be  set  to  1 
Must  be  set  to  0 

Defines  type  of  reference  in  coiorRef ;  the 
color  table  for  a  TextEdit  control 
(TECoiorTabie)  is  described  in 
Chapter  49,  "TextEdit,"  in  this  book: 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  style  reference  in  styieRef ; 
the  format  for  a  TextEdit  style  descriptor  is 
described  in  Chapter  49,  TextEdit,"  in  this 
book: 

00  -  style  reference  is  pointer 

01  -  style  reference  is  handle 

10  -  style  reference  is  resource  ID 

11  -  invalid  value 


A  Important     Do  not  set  fTeiiAboutsize  to  1  unless  the  control  also  has  a 
vertical  scroll  bar.  a 

Valid  values  for  textriags  are 

fNotcontroi  bit  31         Must  be  set  to  0 

f  SingleFormat  bit  30  MuSt  be  set  tO  1 

f  singiestyle  bit  29        Allows  you  to  restrict  the  style  options  available 

to  the  user: 

1  -  Allow  only  one  style  in  the  text 

0  -  Do  not  restrict  the  number  of  styles  in  the 

text 
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fNoWordWrap  bit  28 

fNoScroll  bit  27 

f  Readonly  bit  26 

f  SmartCutPaste  bit  25 

fTabSwitch  bit  24 

fDrawBounds  bit  23 

fColorHilight  bit  22 

f  GrowRuler  bit  21 

fDisableSelection      bit  20 
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Allows  you  to  control  TextEdit  word  wrap 
behavior: 

1  -  Do  not  word  wrap  the  text;  only  break  lines 
on  CR  (SOD)  characters 

0  -  Perform  word  wrap  to  fit  the  ruler 
Controls  user  access  to  scrolling; 

1  -  Do  not  allow  either  manual  or  auto-scrolling 

0  -  Scrolling  permitted 

Restricts  the  text  in  the  window  to  read-only 
operations  (copying  from  the  window  will  still 
be  allowed): 

1  -  No  editing  allowed 

0  -  Editing  permitted 

Controls  TextEdit  support  for  smaa  cut  and 
paste  (see  Chapter  49,  "TextEdit,"  for  details 
on  smart  cut  and  paste  support): 

1  -  Use  smart  cut  and  paste 

0  -  Do  not  use  smart  cut  and  paste 
Defines  behavior  of  the  Tab  key  (see 
Chapter  49,  "TextEdit,"  for  details): 

1  -  Tab  to  next  control  in  the  window 

0  -  Tab  inserted  in  TextEdit  document 

Tells  TextEdit  whether  to  draw  a  box  around  the 
edit  window,  just  inside  rect;  the  pen  for  this 
box  is  two  pixels  wide  and  one  pixel  high 

1  -  Draw  rectangle 

0  -  Do  not  draw  rectangle 
Must  be  set  to  0. 

Tells  TextEdit  whether  to  resize  the  ruler  in 
response  to  the  user  resizing  the  edit  window;  if 
set  to  1,  TextEdit  will  automatically  adjust  the 
right  margin  value  for  the  ruler: 

1  -  Resize  the  mler 

0  -  Do  not  resize  the  ruler 
Controls  whether  user  can  select  text: 

1  -  User  cannot  select  text 
0  -  User  can  select  text 
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fDrawInactiveSelection 

bit  19 


Reserved 


indentRect 


vertBar 


vert Amount 

horzBar 
ho rz Amount 
styleRef 


bits  0-18 


Controls  how  inactive  selected  text  is 
displayed: 

1  -  TextEdit  draws  a  box  around  inactive 
selections 

0  -  TextEdit  does  not  display  inactive 

selections 

Must  be  set  to  0 


Each  coordinate  of  this  rectangle  specifies  the  amount  of  white  space 
to  leave  between  the  boundary  rectangle  for  the  control  and  the  text 
itself,  in  pixels.  Default  values  are  (2,6,2,4)  in  640  mode  and  (2,4,2,2) 
in  320  mode.  Each  indentation  coordinate  may  be  specified 
individually.  In  order  to  assert  the  default  for  any  coordinate,  specify 
its  value  as  $FFFF. 

Handle  of  the  vertical  scroll  bar  to  use  for  the  TextEdit  window.  If  you 
do  not  want  a  scroll  bar  at  all,  then  set  this  field  to  NIL.  If  you  want 
TextEdit  to  create  a  scroll  bar  for  you,  just  inside  the  right  edge  of  the 
boundary  rectangle  for  the  control,  then  set  this  field  to  $FFFFFFFF. 

Specifies  the  number  of  pixels  to  scroll  whenever  the  user  presses  the 
up  or  down  arrow  on  the  vertical  scroll  bar.  laorder  to  use  the  default 
value  (9  pbcels),  set  this  field  to  $0000. 

Must  be  set  to  NIL. 

Must  be  set  to  0. 

Reference  to  initial  style  information  for  the  text.  See  the  description 
of  the  TEFormat  record  in  Chapter  49,  "TextEdit,"  for  information 
about  the  format  and  content  of  a  style  descriptor.  Bits  1  and  0  of 
moreFiags  define  the  type  of  reference  (pointer,  handle,  resource 
ID).  To  use  the  default  style  and  ruler  information,  set  this  field  to 
NULL. 


textDescriptor 

Input  text  descriptor  that  defines  the  reference  type  for  the  initial 
text  (which  is  in  textRef )  and  the  format  of  that  text.  See 
Chapter  49,  "TextEdit,"  for  detailed  information  on  text  and 
reference  formats. 

textRef  Reference  to  initial  text  for  the  edit  window.  If  you  are  not  supplying 

any  initial  text,  then  set  this  field  to  NULL. 
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textLength       If  text  Re  f  is  a  pointer  to  the  initial  text,  then  this  field  must  contain 
the  length  of  the  initial  text.  For  other  reference  types,  TextEdit 
extracts  the  length  from  the  reference  itself. 

♦   Note:  You  must  specify  or  omit  the  textOescriptor,  textRef ,  and  textLength 
fields  as  a  group. 

maxChars         Maximum  number  of  characters  allowed  in  the  text.  If  you  do  not  want 
to  define  any  limit  to  the  number  of  characters,  then  set  this  field  to 
NULL. 

maxLines  MuSt  be  set  tO  0. 

itiaxCharsPerLines 

Must  be  set  to  NULL. 

Must  be  set  to  0. 

Reference  to  the  color  table  for  the  text.  This  is  a  Text  Edit  color  table 
(see  Chapter  49,  "TextEdit,"  for  format  and  content  of 
TECoiorTabie).  Bits  2  and  3  of  moreFiags  define  the  type  of 
reference  stored  here. 

This  is  the  text  mode  used  by  QuickDraw  II  for  drawing  text.  See 
Chapter  l6,  "QuickDraw  n,"  in  Volume  2  of  the  Toolbox  Reference  for 
details  on  valid  text  modes. 

fiiterProcPtr  Pointer  to  a  filter  routine  for  the  control.  See  Chapter  49,  "TextEdit," 
for  details  on  TextEdit  generic  filter  routines.  If  you  do  not  want  to 
use  a  filter  routine  for  the  control,  set  this  field  to  NIL. 


maxHeight 
colorRef 

drawMode 
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Control  Manager  code  example 

This  section  contains  an  example  of  how  to  create  a  list  of  controls  for  a  window  with  a 
single  NewControi2  call.  If  you  wish  to  try  this  in  your  own  program,  you  will  need  to 
create  a  window  that  is  l60  lines  high  and  600  pixels  wide. 

;  Equates  for  the  new  control  manager  features 
;  ctlMoreFlags 


fCtlTarget 

equ 

$8000 

fCtlCanBeTarget 

equ 

$4000 

fCtlWantEvents 

equ 

$2000 

fCtlProcRefNotPtr 

equ 

$1000 

fCtlTellAboutSize 

equ 

$0800 

titlelsPtr 

equ 

$0000 

titlelsHandle 

equ 

$0001 

titlelsResource 

equ 

$0002 

colorTablelsPtr 

equ 

$0000 

colorTablelsHandle 

equ 

$0004 

colorTablelsResource 

equ 

$0008 

NewControl2  ProcRef  values  for  standard  control  types 


simpleButtonControl 

equ 

$80000000 

checkControl 

equ 

$82000000 

radioControl 

equ 

$84000000 

scrollBarControl 

equ 

$86000000 

growControl 

equ 

$88000000 

statTextControl 

equ 

$81000000 

editLineControl 

equ 

$83000000 

editTextControl 

equ 

$85000000 

popUpControl 

equ 

$87000000 

listControl 

equ 

$89000000 

iconButtonControl 

equ 

$07FF0001 

pictureControl 

equ 

$80000000 
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;  Here  is  the  definition  of  my  control  list,  note  it  is  simply  a  list 
;     of  pointers.  These  do  not  have  to  be  in  any  special  order.  This  list 
;     should  always  be  terminated  with  a  zero. 

MyControls    dc.L  theButton, theScroll, theCheck 
dc.L  Radiol, Radio2, StatControl 
dc . L  LEditControl, PopUp, IconButton, 0 

;   Scroll  bar  color  table  as  defined  by  the  original  control  manager. 
;     The  structure  of  these  tables  has  not  changed  for  the  existing 
;     control  types. 

MyColorTable 


dc.W  $00F0 


dc.W  0 
dc.W  $00F0 


dc.W  $0005 
dc.W  $00F0 
dc.W  $00F0 
dc.W  $0000 
dc.W  $0030 


outline  color 
arrow  unhilited  black  on 
white 

arrow  hilite  blue  on  black 
arrow  Background  color 
Thumb  unhilited 
Thumb  hilited 
Page  region  solid 

black/white 
Inactive  bar  color 


Definition  of  a  single  vertical  scroll  bar 


theScroll 


dc.W  10,10,110,36 
dc.L  scrollBarControl 
dc.W  3 


dc.W  10 

dc.L  1 


number  of  parms 
application  ID 
rectangle 

scrollbar  def  proc 
vertical  scroll  bar  w/ 


arrows 


dc.W  10 
dc.W  5 


dc.W  fCtlProcRefNotPtr 
dc.L  0 
dc.W  100 


set  procnotptr  flag 
ref con 
max  size 
size  of  view 
initial  value 


dc.L  MyColorTable 


color  table  to  use 
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Definition  of  a  simple  button 


SimpTitle 
theButton 


num  params 
app  ID 

a  25x30  button 

;   simple  button 
visible,   round  corner 


str  'Button' 
dc.W  7 
dc.L  2 

dc.W  10,40,0,0 
dc.L  simpleButtonControl 
dc.W  0 

dc . W  f CtlProcRef NotPtr+f CtlWantEvents 
dc.L  0 

dc.L  simpTitle  ;  button  Title 


Definition  of  a  check  box  control 


CheckTitle    str  'CheckBox' 
theCheck       dc.W  8 
dc.L  3 

dc.W  25,40,0,0 
dc.L  checkControl 
dc.W  0 

dc.W  f CtlProcRef NotPtr 
dc.L  0 

dc.L  CheckTitle 
dc.W  0 


num  params 
app  ID 

bounding  rect 
control  type 
flags 
MoreFlags 
Re f Con 

TitlePointer 


Definition  of  a  radio  button  control 


RadiolTitle  str  'Radiol' 
Radiol  dc.W  8 

dc.L  4 

dc.W  45,40,0,0 
dc.L  radioControl 
dc.W  1 

dc.W  f CtlProcRef NotPtr 
dc.L  0 

dc.L  RadiolTitle 
dc.W  1 
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;  Definition  of  another  radio  button  control 

Radio2Title  str  'Radio2' 
Radio2  dc.W  8 

dc.L  5 

dc.W  65,40,0,0 
dc.L  radioControl 
dc.W  1 

dc.W  fCtlProcRefNotPtr 
dc.L  0 

dc.L  Radio2Title 
dc.W  0 

;  Definition  of  a  static  text  control 

StatTitle      dc.B  'This  is  Stat  Text' 
StatControl  dc.W  8 
dc.L  6 

dc.W  120,10,135,210 
dc.L  statTextControl 
dc.W  0 

dc.W  fCtlProcRefNotPtr 
dc.L  0 

dc.L  StatTitle 
dc.W  17 

;  Definition  of  an  edit  line  control 

EditDefault  str  'Def aultText ' 
LEditControl 

dc.W  8 
dc.L  7 

dc.W  120,240,135,440 
dc.L  editLineControl 
dc.W  0 

dc.W  fCtlProcRefNotPtr 
dc.L  0 
dc.W  30 

dc.L  EditDefault 
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;  Definition  of  a  pop  up  menu  control  (and  its  menu) 
PopUpMenu      dc.B  ' $$PopUpMenu: \N6 ' , $00 


dc.B  '--Selection  1\N259',$00 

dc.B  ' — Selection  2\N260',$00 

dc.B  ' — Selection  3\N261',$00 

dc.B  '--Selection  4\N262',$00 

dc.b  ' . ' 


dc.L  8 

dc.W  25,140,40,380 
dc .  L  popUpCont'rol 
dc.W  0 

dc.W  fCtlProcRefNotPtr+fMenuDef IsText 

dc.L  0 

dc.W  100 

dc.L  PopUpMenu 

dc.W  259  ;  initial  value 


;  Definition  of  an  icon  button  control 

IconButtonTitle 

str  'Icon  Button' 


Popup 


dc.W  9 


Icon 


dc.W  0 
dc.W  200 
dc.W  10 
dc . w  40 


; black  and  white  icon 


; icon  height  in  pixels 
;icon  width  in  pixels 
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;  Data  for  icon  goes  here  (omitted) 


IconButton 


dew  10 
ds.l  1 

dew  40,  40,  80,  100 
del  iconButtonControl 
dew  0 

dew  FctlProcRefNotPtr 

del  0 
del  Icon 

del  IconButtonTitle 

del  MyColorTable 
dew  0 


pCount 
ID 

button  rectangle 
defproc 

single  outline, 

round-cornered 
get  defproc  from 

resource 

pointer  to  icon 
pointer  to  p-string 
title 

pointer  to  color  table 
standard  drawing  of  icon 


To  create  the  above  new  controls  in  a  window  use  tlie  NewControl2  call: 


pha 
pha 

PushLong  WindPointer 

PushWord  #ptrToPtr 

PushLong  #MyControls 

_NewControl2 

pla 

pla 


room  for  result 

Pointer  to  Owner  window 
Input  verb  for  ptr  to  table 
pointer  to  table  of  templates 

discard  these  bytes,  only  verb 
for  single  ctl  returns  a  value 
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New  control  records 

The  NewControi2  tool  call  creates  extended  control  records  (as  discussed  eariier  in  tliis 
chapter  in  "New  and  changed  controls").  This  section  describes  the  format  and  content  of 
the  control  records  created  by  NewControi2. 

A  Warning       All  control  record  layouts  and  field  descriptions  are  provided  so  that 
programs  may  read  these  records  for  needed  information.  Your 
program  should  never  set  values  into  control  records. a 


Generic  extended  control  record 

Currently,  the  Control  Manager's  standard,  or  generic,  control  record  is  $28  bytes  long  (see 
Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for  information  about 
existing  control  records).  To  support  the  new  controls  (those  created  with 
NewControi2),  the  generic  control  record  has  several  new  fields.  The  layout  of  the  new 
generic  control  record  follows. 
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m   Figure  28-18   Generic  extended  control  record 


$00 

ctlNext 

$04 

ctlOwner 

Long 

$08 

ctlRect 

Rectangle 

$10 

ctlFXag 

Byte 

$11 

ctlHilite 

Byte 

ctlValue 

Word 

$14 

ctlProc 

Long 

$18 

ct lAction 

Lone 

$1C 

ctlData 

Long 

$20 

ctlRef Con 

Long 

$24 

ctlColor 

Long 

$28 

ctlReserved 

Block,  $10  bytes 

$38 

ctllD 

Long 

$3C 

ctlMoreFlags 

Word 

$3E 

ctlVersion 

Word 
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ctlNext 


ctlOwner 
ctlRect 

ctlFlag 

ctlHilite 


ctlValue 


A  handle  to  the  next  control  associated  with  this  control's  window.  All 
the  controls  belonging  to  a  given  window  are  kept  in  a  linked  list, 
beginning  in  the  wcontroi  field  of  the  window  record  and  chained 
together  through  the  ctiNext  fields  of  the  individual  control 
records.  The  end  of  the  list  is  marked  by  a  zero  value;  as  new  controls 
are  created,  they're  added  to  the  beginning  of  the  list. 

A  pointer  to  the  window  port  to  which  the  control  belongs. 

The  rectangle  that  defines  the  control's  position  and  size  in  the  local 
coordinates  of  the  control's  window. 

A  bit  flag  that  further  describes  the  control.  The  appropriate  values  are 
shown  for  each  control  in  the  sections  that  follow. 

Specifies  whether  and  how  the  control  is  to  be  highlighted  and 
indicates  whether  the  control  is  active  or  inactive.  This  field  also 
specifies  whether  the  control  wants  to  receive  selection  events.  The 
values  for  ctiHiiite  are  as  follows; 


0 


1-254 
255 


Control  active;  no  highlighted  parts— this  value  will  cause 
events  to  be  generated  when  the  mouse  button  is  pressed  in 
the  control 

Part  code  of  a  highlighted  part  of  the  control 

Control  inactive— this  value  indicates  that  no  events  are  to 

be  generated  when  the  mouse  button  is  pressed  in  the 

control 


Only  one  part  of  a  control  can  be  highlighted  at  any  one  time,  and  no 
part  can  be  highlighted  on  an  inactive  control.  See 
Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for 
more  information  on  highlighting. 

The  control's  current  setting.  For  check  boxes  and  radio  buttons,  zero 
means  the  control  is  off,  and  a  nonzero  value  means  if  s  on.  For  scroll 
bars,  the  value  is  between  0  and  the  data  size  minus  the  view  size.  The 
field  is  also  available  for  custom  controls  to  use  as  appropriate. 
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ctlProc 


ctlAction 


ctlData 


For  standard  controls,  this  field  indicates  the  control  type,  identified 
by  its  ID.  For  custom  controls,  this  field  contains  a  pointer  to  the 
control  definition  procedure  (defProc)  for  this  type  of  control. 

For  controls  created  with  NewControi,  valid  ID  values  are: 


simpleProc 

checkProc 

radioProc 

scrollProc 

growProc 


$00000000  Simple  button 

$02000000  Check  box 

$04000000  Radio  button 

$06000000  ScroU  bar 

$08000000  Size  box 


For  controls  created  with  NewControi2,  the  f  ctiProcRef  NotPtr 
flag  in  ctiMoreFiags  allows  the  Control  Manager  to  discriminate 
between  pointers  and  IDs.  Valid  ID  values  (used  with 
f  CtiProcRef  NotPtr  set  to  1)  are: 


simpleButtonControl 

$80000000 

Simple  button 

checkControl 

$82000000 

Check  box 

iconButtonControl 

$07FF0001 

Icon  button 

editLineControl 

$83000000 

LineEdit 

listControl 

$89000000 

List 

pictureControl 

$8D000000 

Picture 

popUpControl 

$87000000 

Pop-up 

radioControl 

$84000000 

Radio  control 

scrollBarControl 

$86000000 

Scroll  bar 

growControl 

$88000000 

Size  box 

statTextControl 

$81000000 

Static  text 

editTextControl 

$85000000 

TextEdit 

Pointer  to  the  control's  custom  action  procedure,  if  any. 
Trackcontroi  may  call  the  custom  action  procedure  to  respond  to 
the  user  dragging  the  mouse  inside  the  control.  See 
Chapter  4,  "Control  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for 
more  information  about  TrackControi. 

Reserved  for  use  by  the  control  definition  procedure,  typically  to  hold 
additional  information  for  a  particular  control  type.  For  example,  the 
standard  definition  procedure  for  scroll  bars  uses  the  low-order  word 
as  the  view  size  and  the  high-order  word  as  the  data  size.  The  standard 
definition  procedures  for  simple  buttons,  check  boxes,  and  radio 
buttons  store  the  address  of  the  control's  title. 


ctlRefCon 


This  field  is  reserved  for  application  use. 
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cticoior         This  field  contains  a  reference  to  the  color  table  to  use  when  drawing 
the  control.  If  the  field  is  set  to  NIL,  the  Control  Manager  uses  a 
default  color  table  defined  by  the  control's  definition  procedure. 
Otherwise,  cticoior  contains  a  pointer,  handle,  or  resource  ID  for 
the  color  table  to  use.  Bits  2  and  3  of  ctiMoreFiags  usually  allow 
the  Control  Manager  to  discriminate  between  these  different  data 
types. 

ctiReserved     This  space  is  reserved  for  use  by  the  control  definition  procedure.  In 
some  cases,  the  use  is  presaibed  by  the  system.  For  example, 
keyboard  equivalent  information  is  stored  here  for  controls  that 
support  keyboard  equivalents. 

ctiiD  This  field  may  be  used  by  the  application  to  provide  a  straightforward 

mechanism  for  keeping  track  of  controls.  The  control  ID  is  a  value 
assigned  by  your  application  with  the  id  field  of  the  control  template 
used  to  create  the  control.  Your  application  can  use  the  ED,  which  has 
a  known  value,  to  identify  a  particular  control. 

CtiMoreFiags    This  field  contains  bit  flags  that  provide  additional  control 

information  needed  for  new-style  controls  (those  created  with 
NewControi2).  You  can  use  the  GetctiMoreFiags  Control 
Manager  call  to  read  the  value  of  this  field  from  a  specified  control 
record.  Use  the  SetctiMoreFiags  call  to  change  the  value. 

The  high-order  byte  is  used  by  the  Control  Manager  to  store  its  own 
control  information.  The  low-order  byte  is  used  by  the  control 
definition  procedure  to  defme  reference  types. 

The  defined  Control  Manager  flags  are: 

f  ctiTarget  $8000         If  set  to  1,  this  control  is  currently  the  target  of 

any  typing  or  editing  commands. 

f  ctiCanBeTarget        $4000         If  set  to  1  then  this  control  can  be  made  the 

target  control. 

f  ctiwantEvents         $2000         If  set  to  1  then  this  control  can  be  called  when 

events  are  passed  via  the  sendEventTocti 
Control  Manager  call.  Note  that,  if  the 
f  CtiCanBeTarget  flag  is  set  tO  1,  this  control 

will  receive  events  sent  to  it  regardless  of 
setting  of  this  flag. 
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If  set  to  1,  then  Control  Manager  expects 
ctiProc  to  contain  the  E)  of  a  standard 
control  procedure.  If  set  to  0,  then  c  tip  roc 
contains  a  pointer  to  the  custom  control 
procedure. 

If  set  to  1,  then  this  control  needs  to  be 
notified  when  the  size  of  the  owning  window 
has  changed.  This  flag  allows  custom  control 
procedures  to  resize  their  associated  control 
images  in  response  to  changes  in  window  size. 
If  set  to  1,  then  this  is  a  multipart  control.  This 
flag  allows  control  definition  procedures  to 
manage  multi-part  controls  (necessary  since  the 
Control  Manager  does  not  know  about  all  the 
parts  of  a  multi-part  control). 

The  low-order  byte  uses  the  following  convention  to  describe 
references  to  color  tables  and  titles  (note,  though,  that  some  control 
templates  do  not  follow  this  convention): 


titlelsPtr 

$00 

Title  reference  is  by  pointer 

titlelsHandle 

$01 

Title  reference  is  by  handle 

titlelsResource 

$02 

Title  reference  is  by  resource  ID 

colorTablelsPtr 

$00 

Color  table  reference  is  by  pointer 

colorTablelsHandle 

$04 

Color  table  reference  is  by  handle 

colorTablelsResource 

$08 

Color  table  reference  is  by  resource  ID 

ctiversion      This  field  is  reserved  for  future  use  by  the  Control  Manager  to 

distinguish  between  different  versions  of  control  records. 
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Extended  simple  button  control  record 

Figure  28-19  shows  the  format  of  the  extended  control  record  for  simple  button  controls. 
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m   Figure  28-19   Extended  simple  button  control  record 


$00 

ctlNext 

Long— Handle  to  next  control;  NIL  for  last  control 

$04 

ctl Owner 

Long — ^Pointer  to  window  to  which  control  belongs 

$08 

ctlRect 

Rectangle— Defines  button's  boimdary  rectangle 

$10 

ctlFlag 

Byte— Defines  button  style 

$11 

ctlHllite 

Byte— Current  type  of  highlighting 

$12 

ct lvalue 

word — Not  used;  set  to  0 

$14 

ctlProc 

Long—  s  in^jleButt  onCont  rol=$80000000 

$18 

ctlAction 

Long— Pointer  to  custom  procedure;  NIL  if  none 

$1C 

ctlData 

Long—Reference  lo  buttoi  title  string 

$20 

ctlRefCon 

Long— Reserved  for  application  use 

$24 

ctlColor 

Tiino— -Ontinnal  mlnrtahlp  rf^prpnrf**  NT!  if  nnnp 

$28 

IceyEqulv 

Block,  $06  Bytes— Key  equivalent  record 

$2E 

ctlRe served 

Block,  $0A  bytes— Reserved 

$38 

ctllD 

Long-rApplicaticMi-assigned  ID 

$3C 

ctlMoreFlags 

Wad— Additional  control  flags 

$3E 

ctlVerslon 

Word— Set  to  0 
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Valid  values  for  ctiFiag  are 


ctllnvis 

Reserved 
Button  type 


bit  7  1 -invisible,  0=visible 

bits  2-6       Must  be  set  to  0 

bits  0-1       Describes  button  type; 

0  -  single-outlined  round-cornered  button 

1  •=  bold-outiined  round-cornered  button 

2  •=  single-outlined  square-cornered  button 

3  "  single-outlined  square-cornered  drop- 
shadowed  button 


Valid  values  for  ctiMoreFiags  are 


f CtlTarget 
fCtlCanBeTarget 
fCtlWantsEvents 
fCtlProcNotPtr 
fCtlTellAboutSize 
Reserved 

Color  table  reference 


Title  reference 


keyEquiv 


bit  15  Must  be  set  to  0 
bit  14  Must  be  set  to  0 
bit  13  Set  to  1  if  button  has  keystroke  equivalent 
bit  12  Must  be  set  to  1 
bit  11  Must  be  set  to  0 
bits  4-10     Must  be  set  to  0 

bits  2-3       Defines  type  of  reference  incticoior(ifitis 
not  NIL).  See  Chapter  4,  "Control  Manager,"  in 
Volume  1  of  the  Toolbox  Reference  for  the 
definition  of  the  simple  button  color  table, 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

bits  0-1      Defines  type  of  tide  reference  in  ctlData: 

00  -  title  reference  is  pointer 

01  -  title  reference  is  handle 

10  -  title  reference  is  resource  ID 

11  -  invalid  value 

Keystroke  equivalent  information  stored  at  keyEquiv  is  formatted 
as  shown  in  Figure  28-2. 
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Extended  check  box  control  record 

Figure  28-20  shows  the  format  of  the  extended  control  record  for  check  box  controls. 
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m   Figure  28-20   Extended  check  box  control  record 


$00 

ctlNext 

Long — ^ndiiuic  10  ucxi  conuoij  inil  lor  lasi  coniroi 

$04 

ctlOwner 

LcMig — Pointer  to  window  to  which  control  belongs 

$08 

ctlRect 

Rectangle — ^Defines  check  box's  boundary  rectangle 

$10 

ctlFlag 

Byte— Defines  check  box  visibility 

$11 

ctlHilite 

Byte— Current  type  of  highlighting 

419 

ctlValue 

Word— 0  if  not  checked;  1  if  checked 

$14 

- 

Long— checkControl  =$82000000 

$18 

ctlActlon 

$1C 

ctlData 

Lcxig— Reference  to  check  box  title  string 

$20 

ctlRefCon 

LtKig— Reserved  for  application  use 

$24 

ctlColor 

Lcxig— Optional  color  table  reference;  NIL  if  none 

$28 

keyEqulv 

Block,  $06  Bytes— Key  equivalent  record 

$2E 

ctlReserved 

Block,  $0A  bytes— Reserved 

$38 

ctllD 

Long— Applicatbn-assigned  ID 

$3C 

ctlMoreFlags 

Word— Additional  conu-ol  flags 

$3E 

ctlVersion 

Word— Set  too 
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Valid  values  for  ctiFiag  are 

l=invisible,  0=visible 
Must  be  set  to  0 


Must  be  set  to  0 
Must  be  set  to  0 

Set  to  1  if  check  box  has  keystroke  equivalent 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 

Defines  type  of  reference  incticoior(ifitis 
not  NIL).  See  Chapter  4,  "Control  Manager,"  in 
Volume  1  of  the  Toolbox  Reference  ior  the 
definition  of  the  check  box  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  title  reference  in  ctiData: 

00  -  title  reference  is  pointer 

01  -  title  reference  is  handle 

10  -  title  reference  is  resource  ID 

11  -  invalid  value 

keyEquiv         Keystroke  equivalent  information  stored  at  keyEquiv  is  formatted 
as  shown  in  Figure  28-2. 
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Color  table  reference  bits  2-3 


Title  reference  bits  0-1 
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Icon  button  control  record 

Figure  28-21  shows  the  format  of  the  control  record  for  icon  button  controls. 


■   Figure  28-21   Icon  button  control  record 


$00 

ctlNext 

T  Ana—Won^lA  tr\  nAvt  rr^ntrrtl'  MTT  frtr  l^ct  ^nntf  Al 

LiUllK^^^uUlUiC  lU  IICAL  L.\JilUUi]          lUi  Idol  LullUUl 

m 

ctlowner 

1  rtno— .Prtintpr  fn  'tlrin^^/^Tl7  tr»  xi/ht/^H  /*r\ntm!  }vilrtoo< 
JUUIIg^^TUIlllCI  lU  WlIlUuW  LU  WlUUi  CUIIUUI  UClUliJ^O 

m 

ctlRect 

Rectangle— Defines  icai  boundary  rectangle 

$10 

ctlFlag 

Byte— Defines  control  visibility  and  button  style 

$11 

ctlHlllte 

Byte— Controls  highlighting 

$12 

ctlValue 

Word— Not  used;  set  to  0 

$14 

ctlProc 

Long —  i  conButtonCont  rol=$07FF0001 

$18 

ctlActlon 

Long— Pointer  to  custom  procedure;  NIL  if  none 

$1C 

ctlData 

Long— Optional  reference  to  title  string  for  button 

$20 

ctlRefCon 

Long— Reserved  for  application  use 

$24 

ctlColor 

Long— Optional  color  taWe  reference;  NIL  if  none 

$28 

keyEqulv 

Block,  $06  bytes— Key  equivalent  record 

continued 
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$2E 
$38 

$3C 

$3E 
$40 

$44 


continued 


—       ctlMoreFlags  — 


ctiReserved       \  Block,  $0A  bytcs — ^Reserved 


ctllD 


—  ctlVersion 


IconRef 


dlsplayMode  — 


Long-^pplication-assigned  ID 

Wwd— Additional  control  flags 
Word-SatoO 

Long— Reference  to  icon 

Word— Bit  flag  defining  icon's  appearance 


Valid  values  for  ctiFiag  are 


ctllnvis 

Reserved 

showBorder 
buttonType 


bit? 
bits  3-6 
bit  2 
bits  0-1 


1 -invisible,  0» visible 
Must  be  set  to  0 
1-No  border,  0-Show  border 
Defines  button  type: 

00  -  single-outlined  round-cornered  button 

01  -  bold-outlined  round-cornered  button 

10  -  single-outlined  square-cornered  button 

11  -  single-outlined  square-cornered  and  drop- 
shadowed  button 
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Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

Reserved 

Icon  reference 


Color  table  reference 


bit  15  Must  be  set  to  0 
bit  14  Must  be  set  to  0 
bit  13  Must  be  set  to  0 
bit  12  Must  be  set  to  1 
bit  11  Must  be  set  to  0 
bits  6-10  Must  be  set  to  0 
bits  4-5       Defines  type  of  icon  reference  in  iconRef : 

00  -  icon  reference  is  pointer 

01  -  icon  reference  is  handle 

10  -  icon  reference  is  resource  ID 

11  -  invalid  value 
bits  2-3       Defines  type  of  reference  incticoior(ifitis 

not  NIL).  The  color  table  for  an  icon  button  is 
the  same  as  that  for  a  simple  button.  See 
Chapter  4,  "Control  Manager,"  in  Volume  1  of 
the  Toolbox  Reference  hr  the  definition  of  the 
simple  button  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 
bits  0-1       Defines  type  of  title  reference  in  ctiData: 

00  -  title  reference  is  pointer 

01  -  title  reference  is  handle 

10  -  title  reference  is  resource  ID 

11  -  invalid  value 

Holds  the  reference  to  the  tide  string,  which  must  be  a  Pascal  string. 

Passed  direcdy  to  the  Drawicon  routine,  and  defmes  the  display 
mode  for  the  icon.  The  Control  Manager  sets  this  field  from  the 
dispiayMode  field  in  the  icon  button  control  template  used  to 
create  the  control. 

keyEquiv         Keystroke  equivalent  information  stored  at  keyEquiv  is  formatted 
as  shown  in  Figure  28-2. 


Title  reference 


ctlData 
dispiayMode 
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LlneEdlt  control  record 

Figure  28-22  shows  the  format  of  the  control  record  for  LineEdit  controls. 


■   Figure  28-22    LineEdit  control  record 


$00 

ctlNext 

Long — ^Handle  to  neact  control;  NIL  for  last  control 

$04 

ctlOwner 

Long — ^Pointer  to  window  to  which  control  belongs 

$08 

ctlRect 

Rectangle— Defines  contrd  boundary  rectangle 

$10 

ctlFlag 

Byte— Defines  control  visibility 

$11 

ctlHllite 

Byte— Controls  highlighting 

»1^ 

ct lvalue 

WoKi— Not  used;  must  be  sa  to  0 

$14 

ctlProc 

Iftfio  oH-i  l-T  i  nckrnr^i■■rn^  =^8^00000(1 

$18 

ctlActlon 

T  rmo_Pr\intpr  trt  nict/vn  nrriTpHiirp*  NTT  ifnrinp 
uuuiK— rvjuiiu  lu  cudvv/iii  uiv\AAiuiC|  iiiij  11  iiuiit 

$1C 

ctlData 

Lraig — Handle  to  LineEdit  edit  recced 

$20 

ctlRefCon 

Long— Reserved  fw  applicatiai  use 

$24 

ctlColor 

Long— Not  used;  must  be  set  to  0 

$28 

ctl Re served 

Block,  $10  bytes— Not  used;  must  be  set  to  0 

$38 

ctl  ID 

Long— Application-assigned  ID 

$3C 

ctlMoreFlags 

Word— Additional  control  flags 

$3E 

ct  IVerslon 

Word— Set  too 
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Valid  values  for  ctiFiag  are 


ctllnvis 
Reserved 


bit? 
bits  0-6 


Valid  values  for  ctiMoreFiags  are 

fCtlTarget  bit  15 

fCtlCanBeTarget  bit  14 

fCtlWantsEvents  bit  13 

fCtlProcNotPtr  bit  12 

fCtlTellAboutSize  bit  11 

Reserved  bits  2-10 

Text  reference  bits  0-1 


1  "invisible,  0=visible 
Must  be  set  to  0 


Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  1 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 

Defines  type  of  text  reference  in  ctiData 

00  -  text  reference  is  pointer 

01  -  text  reference  is  handle 

10  -  text  reference  is  resource  ID 

11  -  invalid  value 


ctlData 


Control  Manager  stores  the  handle  to  the  LineEdit  edit  record  in  the 
CtlData  field.  If  you  want  to  issue  LineEdit  tool  calls  directly,  you 
can  reu-ieve  the  handle  from  that  field. 


Note  that  DneEdit  controls  do  not  support  color  tables. 
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List  control  record 

Figure  28-23  shows  the  format  of  the  control  record  for  list  controls. 


■   Figure  28-23   List  control  record 


$00 

ctlNext 

Lcsig— Handle  to  next  control;  NIL  for  last  control 

m 

ctlOwner 

Long— Pointer  to  window  to  which  control  belongs 

$08 

$10 

ctlRect 

Rectangle— Defines  control  boundary  rectangle 

ctlFlag 

Byte — ^Defines  style  of  saoll  bar  for  list  window 

$11 

ctlHlllte 

Byte— ^^ot  used;  must  be  set  to  0 

$12 

ctlValue 

Word— Reserved 

$14 

ctlProc 

Long— listControl  =$89000000 

$18 

ctlActlon 

Long— Pointer  to  custom  procedure;  NIL  if  none 

$1C 

ctlData 

Long— High-word  islistSize ;  low-wad  is  viewSize 

$20 

ctlRefCon 

Long^eserved  for  application  use 

$24 

ctlColor 

Long— Merence  to  the  color  taHe  for  the  contrd 

$28 

ct IMemDraw 

Long— Pointer  to  list  member  drawing  routine 

$2C 

ctlMemHeight 

Word— List  member  height  in  pixels 

$2£ 

ctlMemSlze 

Word— List  member  record  size  in  bytes 

continued 
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$30 
$34 

$38 

$3C 
$3E 


-  ctlListRef 


—        ctlListBar  — 


continued 


CtllD 


ctlMoreFlags  — 


—  ctlVerslon 


Long— Reference  to  list  member  records 
Long— Handle  of  control's  saoll  bar  control 

Long— Applicaticxi-assigned  ID 

Word— Additional  control  flags 
Word-S«toO 


Valid  values  for  ctiFiag  are 

ctiinvis  bit  7  1-invisible,  0=visible 

Reserved  bits  0-6       Must  be  set  to  0 
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Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

fCtllsMultiPart 

Reserved 

Color  table  reference 


List  reference 


bit  15  Must  be  set  to  0 
bit  14  Must  be  set  to  0 
bit  13  Must  be  set  to  0 
bit  12  Must  be  set  to  1 
bit  11  Must  be  set  to  0 
bit  10  Must  be  set  to  1 
bits  4-9       Must  be  set  to  0 

bits  2-3       Defines  type  of  reference  in  cticoior  (if  it  is 
not  NIL).  The  color  table  for  a  List  control  is 
described  in  Chapter  11,  "List  Manager,"  in 
Volume  1  of  the  Toolbox  Reference. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

bits  0-1       Defines  type  of  reference  in  listRef .  The 

format  for  a  list  member  record  is  described  in 
Chapter  11,  "List  Manager,"  in  Volume  1  of  the 
Toolbox  Reference. 

00  -  list  reference  is  pointer 

01  -  list  reference  is  handle 

10  -  list  reference  is  resource  ID 
11 -invalid  value 
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Picture  control  record 

Figure  28-24  shows  the  format  of  the  control  record  for  picture  controls. 


■   Figure  28-24    Picture  control  record 


$00 

ctlNext 

T r\no__HonHlp  tr\  npvt  /TintrAl'  MTT  fr\r  loct  mntrr\\ 

$04 

ctlOwner 

LUIl^ — X  UilliCl  \\)  WlllUUW  lU  WlUUl  LUllUUl 

$08 

ctlRect 

Rectangle— Defines  piaure  bouiKiaiy  rectangle 

$10 

ctlFlag 

Byte— Defines  picture  visibility 

$11 

ctlHlllte 

Byte— Controls  event  generation  for  control 

ill 

ct lvalue 

WOTd— Not  used;  set  to  0 

$14 

ctlProc 

Lone  nictureControl  =$8D0O00O0 

$18 

ctlAction 

Lone  ^Pointer  to  custom  orocedurC'  NIL  if  none 

$1C 

ctlData 

Long— Reference  to  picture 

$20 

ctlRefCon 

Long— Reserved  for  application  use 

$24 

ctlColor 

Long-4Jot  used;  must  be  set  to  0 

$28 

ctlReserved 

Block,  $10  bytes— Not  used 

$38 

ctllD 

Long— Application-assigned  ID 

$3C 

ctlMoreFlags 

Word— Additional  control  flags 

$3E 

ctlVerslon 

Word— Set  to  0 
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Valid  values  for  ctiFiag  are 


ctllnvis 
Reserved 


bit? 
bits  0-6 


1  "invisible,  0-visible 
Must  be  set  to  0 


Valid  values  for  ctiMoreFiags  are 

fCtlTarget  bit  15 

fCtlCanBeTarget  bit  14 

fCtlWantsEvents  bit  13 

fCtlProcNotPtr  bit  12 

fCtlTellAboutSize  bit  11 

Reserved  bits  2-10 

Picture  reference  bits  0-1 


Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 

Define  type  of  picture  reference  inctiData: 

00  -  invalid  value 

01  -  reference  is  handle 

10  -  reference  is  resource  E) 

11  -  invalid  value 

ctiHiiite        Specifies  whether  the  control  wants  to  receive  mouse  events.  The 
values  for  ctiHiiite  are  as  follows: 

0     Events  will  be  generated  when  the  mouse  button  is  pressed  in  the 
control 

255  No  events  will  be  generated  when  the  mouse  buttron  is  pressed 
in  the  control 
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Pop-up  control  record 

Figure  28-25  shows  the  format  of  the  control  record  for  pop-up  menu  controls. 


■   Figure  28-25   Pop-up  control  record 


$00 

ctlNext 

$04 

ctlOwner 

T  r»no— PAtntpr  tA  n/inHnw  tn  whirh  rnntrnl  }v*lrffioc 
lA/iiK^^ruiiiici  vj  wiiiuuw  i\j  wiiiui  v.uiiuui  LKuv^ijj^o 

$08 

ctlRect 

Rectangle— Defines  control  boundary  rectangle 

$10 

ctlFlag 

Byte— Defines  control  visibility  and  other  attributes 

$11 

ctlHilite 

Byte— Not  used;  must  be  set  to  0 

J12 

ct lvalue 

Word— Currently  seleaed  item 

$14 

ctlProc 

Long-popUpControl  =$87000000 

$18 

ctlActlon 

Long— Pointer  to  custom  procedure;  NIL  if  none 

$1C 

ctlData 

Long— i^ot  used;  must  be  set  to  0 

$20 

ctlRefCon 

Long— Reserved  for  application  use 

$24 

ctlColor 

Long— Reference  to  the  color  table  for  the  control 

$28 

menuRel 

Long— Reference  to  menu  definition 

continued 
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continued 

$2C 

menuEnd 

Lone — Must  be  set  to  0 

$30 

popUpRect 

Rectangle— Calculated  by  Menu  Manger 

$38 

ctllD 

Long— Application-assigned  ID 

$3C 

$3E 

CtlMoreFlags 

Waxi— Additional  control  flags 

$40 

CtlVerslon 

Word— Set  too 

tltleWidth 

Word— Pixel  width  of  title  position  of  menu 

Valid  values  for  ctiFiag  are 


ctllnvis 

f Type2PopUp 


fDontDrawTitle 


bit? 
bit  6 


fDontHiliteTitle        bit  5 


bit  4 


fDontDrawResult  bit  3 


1 -invisible,  0-visible 

Indicates  type  of  pop-up  menii: 

1  -  Draw  pop-up  with  white  space  (Type  2) 

0  -  Draw  normal  pop-up 

Controls  highlighting  of  the  control  title: 

1  -  Do  not  highlight  title  when  control  is  popped 
up 

0  -  Highlight  title 

Indicates  whether  the  Control  Manager  is  to 
draw  the  n^nu  tide: 

1  -  Do  not  draw  the  tide 

0  -  Draw  die  tide 

Indicates  whedier  result  is  shown: 

1  -  Do  not  draw  the  result  in  die  result  area  after 
a  selection 

0- Draw  die  result 
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fRight JustifyResult  bit  0 
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Controls  the  extent  to  wliich  the  pop-up  menu 

can  grow;  this  is  particularly  relevant  with 

respect  to  Type  2  pop-ups  (see 

Chapter  37,  "Menu  Manager  Update,"  for  details 

on  Type  2  pop-up  menus): 

1  -  Keep  the  pop-up  in  the  current  window 

0  -  Allow  the  pop-up  to  grow  to  screen  si2e 
Controls  title  justification: 

1  -  Right  justify  the  title;  note  that  if  the  title  is 
right  justified,  then  the  control  rectangle  is 
adjusted  to  eliminate  unneeded  pixels  (see 
Figure  28-12),  the  value  for  titiewidth  is  also 
adjusted 

0  -  Left  justify  the  title 
ConU^ols  result  justification: 

1  -  Right  justify  the  selection 

0  -  Left  justify  the  selection  titiewidth 
pixels  from  the  left  of  the  pop-up  rectangle. 
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Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 
fCtlTellAboutSize 

Reserved 

Color  table  reference 


fMenuDef IsText 


Menu  reference 


bit  15  Must  be  set  to  0 
bit  14  Must  be  set  to  0 
bit  13         Must  be  set  to  1  if  the  pop-up  has  any 

keystroke  equivalents  defined 
bit  12         Must  be  set  to  1 
bit  11         Must  be  set  to  0 
bits  5-10     Must  be  set  to  0 

bits  3-4      Defines  type  of  reference  in  coiorTabieRef 
(the  color  table  for  a  menu  is  described  in 
Chapter  13,  "Menu  Manager,"  in  Volume  1  of  the 
Toolbox  Reference) 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

bit  2  Defines  type  of  data  referred  to  by  menuRef : 

I  -  menuRef  is  a  pointer  to  a  text  stream  in 
NewMenu  format  (see 

Chapter  13,  "Menu  Manager,"  in  Volume  1  of  the 
Toolbox  Reference  for  details) 
0  -  menuRef  is  a  reference  to  a  Menu  Template 
(again,  see  Chapter  13,  "Menu  Manager,"  in 
Volume  1  of  the  Toolbox  Reference  for  details  on 
format  and  content  of  a  Menu  Template) 
bits  0-1       Defines  type  of  menu  reference  in  menuRef  (if 
fMenuDef  IsText  is  set  lo  1,  then  these  bits 
are  ignored): 

00  -  menu  reference  is  pointer 

01  -  menu  reference  is  handle 

10  -  menu  reference  is  resource  ID 

II  -  invalid  value 
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ctlRect 


ctlValue 
titleWidth 

menuRef 


Defines  the  boundary  rectangle  for  the  pop-up  and  its  tide,  before  the 
menu  has  been  "popped"  by  the  user.  The  Menu  Manager  will  calculate 
the  lower-right  coordinates  of  the  rectangle  for  you,  if  you  specify 
those  coordinates  as  (0,0). 

Contains  the  item  number  of  the  currendy  selected  item. 

Contains  the  value  set  in  die  titiewidth  field  of  die  pop-up  menu 
control  template  used  to  create  die  control. 

Reference  to  menu  definition  (see  Chapter  13,  "Menu  Manager,"  in 
Volume  1  of  die  Toolbox  Reference  and 

Chapter  37,  "Menu  Manager  Update,"  in  diis  book  for  details  on  menu 
templates).  The  type  of  reference  contained  in  menu  Re  f  is  defined 
by  die  Menu  reference  bits  in  ctiMoreFiags.  This  field  is  set  from 
die  menuRef  field  of  die  pop-up  menu  control  template  used  to 
create  the  control. 
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Extended  radio  button  control  record 

Figure  28-26  shows  the  format  of  the  extended  control  record  for  radio  button  controls. 
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m   Figure  28-26   Extended  radio  button  control  record 


$00 

ctlNext 

Long— Handle  to  next  control;  NIL  for  last  control 

$04 

ctlowner 

Long— Pointer  to  window  to  which  control  belongs 

$08 

ctlRect 

RpTtanfflf*— Df^nw  radio  button's  hniindarv  rwlanelp 

$10 

ctlFlag 

Byte— Defines  button  visibility  and  family  affinity 

$11 

ctlHlllte 

Byte— Current  type  of  highlighting 

$12 

ct lvalue 

Word-Oifoff;lifon 

$14 

ctlProc 

Long— radioControl=$84000000 

$18 

ctlActlon 

Long — Pointer  to  custom  procedure;  NIL  if  none 

$1C 

ctlData 

Long— Reference  to  radio  button  title  string 

$20 

ctlRefCon 

Lmg— Reserved  fa  application  use 

$24 

ctlColor 

Long— Optional  color  table  reference;  NIL  if  none 

$28 

IceyEqulv 

Block,  $06  Bytes— Key  equivalent  record 

$2E 

ctl Re served 

Block,  $0A  bytes— Reserved 

$38 

CtllD 

Long— Application-assigned  ID 

$3C 

Ct IMoreFlags 

Word— Additional  control  flags 

$3E 

ctlVersion 

Word— Set  too 

Chapter  28  Control  Manager  Update  28-117 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Valid  values  for  ctiFiag  are 


ctllnvis 
Family  number 


bit? 
bits  0-6 


Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

Reserved 

Color  table  reference 


bit  15 
bit  14 
bit  13 
bit  12 
bit  11 
bits  4-10 
bits  2-3 


Title  reference 


bits  0-1 


l=invisible,  0=visible 

Family  numbers  define  associated  groups  of 
radio  buttons.  Radio  buttons  in  the  same  family 
are  logically  linked.  That  is,  setting  one  radio 
button  in  a  family  clears  all  other  buttons  in  the 
same  family 


Must  be  set  to  0 
Must  be  set  to  0 

Set  to  1  if  button  has  keystroke  equivalent 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 

Defines  type  of  reference  incticoior(ifitis 
not  NIL).  See  Chapter  4,  "Control  Manager,"  in 
Volume  1  of  the  Toolbox  Reference  ht  the 
definition  of  the  radio  button  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  tide  reference  in  ctiData: 

00  -  title  reference  is  pointer 

01  -  title  reference  is  handle 

10  -  title  reference  is  resource  ID 

11  -  invalid  value 


keyEquiv 


Keystroke  equivalent  information  stored  at  keyEquiv  is  formatted 
as  shown  in  Figure  28-2. 
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Extended  scroll  bar  control  record 

Figure  28-27  shows  the  format  of  the  extended  control  record  for  scroll  bar  controls. 
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m   Figure  28-27   Extended  scroll  bar  control  record 


$00 

ctlNext 

m 

ctlOwner 

Long — ^Pointer  to  window  to  which  control  belongs 

$08 

ctlRect 

Rectangle — ^Defines  saoll  bar's  boundary  rectangle 

$10 

ctlFlag 

Byte— Style  of  saoll  bar 

$11 

ctlHiXite 

Byte— Current  type  of  highlighting 

ct lvalue 

Word— Thumb  position  between  0  and  (dataSize  —  viewSize) 

$14 

ctlProc 

Long— s  crol  ICont  rol=$86000000 

$18 

ctlAction 

T  Afio— Pnintpr  tn /^ictrim  rif/VAHjirA-  MTT  iFnrinp 

$1C 

ctlData 

Long— HighK)rder  word=  dataSize,  low-order  word=  viewSize 

$20 

ctlRefCon 

Reserved  for  application  use 

$24 

ctlColor 

Long— Optbnal  cola  table  reference;  NE  if  none 

$28 

thumbRect 

Rectangle— Defines  thumb  rectangle 

$30 

pageReglon 

Rectangle— Defines  page  region,  thumb  bounds 

$38 

ctllD 

Long— Application-assigned  ID 

$3C 

ctlMoreFlags 

Word— Additional  control  flags 

$3E 

ctiversion 

Word— Set  to  0 
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Valid  values  for  ctiFiag  are 


ctllnvis 

Reserved 

horScroll 

rightFlag 

leftFlag 

downFlag 

upFlag 


bit  7  1 -invisible,  O-visible 

bits  5-6  Must  be  set  to  0 

bit  4  1-horizontai  scroll  bar,  0=vertical  scroll  bar 

bit  3  l"bar  has  right  arrow,  0=bar  has  no  right  arrow 

bit  2  l=bar  has  left  arrow,  0=bar  has  no  left  arrow 

bit  1  l"bar  has  down  arrow,  0"=bar  has  no  down  arrow 

bit  0  1-bar  has  up  arrow,  0-bar  has  no  up  arrow 


Note  that  extraneous  flag  bits  are  ignored,  based  upon  the  state  of  the  horscroii  flag. 
For  example,  for  vertical  scroll  bars,  rightFlag  and  lef  tFiag  are  ignored. 


Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

Reserved 

Color  table  reference 


bit  15 
bit  14 
bit  13 
bit  12 
bit  11 
bits  4-10 
bits  2-3 


Reserved 


bits  0-1 


Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 

Defines  type  of  reference  in  cticoior  (if  it  is 
not  NIL).  See  Chapter  4,  "Conu-ol  Manager,"  in 
Volume  1  of  the  Toolbox  Reference  Sind 
"Clarifications"  in  this  chapter  for  the 
defmition  of  the  scroll  bar  color  table, 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 
Must  be  set  to  0 
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Extended  size  box  control  record 

Figure  28-28  shows  the  format  of  the  extended  control  record  for  size  box  controls. 


■   Figure  28-28   Extended  size  box  control  record 


$00 

CtlNext 

I/^no — Handlp  to  npxt  rnnfrol-  NTI  for  la^  rnnfrn! 

$04 

CtlOwner 

Tnno  Pnint(*r  to  window  to  whirh  rontro!  hpiono^; 

$08 

CtlRect 

Rectangle— Defines  size  box's  boundary  rectangle 

$10 

CtlFlag 

Byte— Define  size  box  visibility 

$11 

OtlHillte 

Byte— Current  type  of  highlighting 

$12 

CtlValue 

Word— Not  used;  set  to  0 

$14 

CtlProc 

Long— growControl=$88000000 

$18 

ctlAction 

Long — Pointer  to  custom  procedure,  NIL  if  none 

$1C 

CtlData 

Long— Not  used;  set  to  0 

$20 

ctlRefCon 

Long-Reserved  for  application  use 

$24 

CtlColor 

Long— OpUonal  color  table  reference;  NIL  if  none 

$28 

ctlReserved 

Block,  $10  bytes-^ot  used;  set  to  0 

$38 

ctllD 

Long— Application-assigned  ID 

$3C 

CtlMoreFlags 

Word— Additional  control  flags 

$3E 

CtlVersion 

Word— Sato  0 
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Valid  values  for  ctiFiag  are  as  follows: 


ctllnvis  bit  7 

Reserved  bits  1-6 

f  CallWindowMgr  bit  0 


l=invisible,  0=visible 
Must  be  set  to  0 

l=call  GrowWindow  and  SizeWindow  to  track 
this  control;  0=just  highlight  control 


Valid  values  for  ctiMoreFiags  are  as  follows; 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 

fCtlTellAboutSize 

Reserved 

Color  table  reference 


Reserved 


bit  15  Must  be  set  to  0 
bit  14  Must  be  set  to  0 
bit  13  Must  be  set  to  0 
bit  12  Must  be  set  to  1 
bit  11  Must  be  set  to  0 
bits  4-10     Must  be  set  to  0 

bits  2-3       Defines  type  of  reference  incticoior(ifitis 
not  NIL).  See  "Error  Corrections"  in  this  chapter 
for  the  definition  of  the  size  box  color  table. 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 
bits  0-1       Must  be  set  to  0 
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Static  text  control  record 

Figure  28-29  shows  the  format  of  the  control  record  for  static  text  controls. 
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■   Figure  28-29   Static  text  control  record 


$00 

ctlNext 

Long — Handle  to  next  control;  NIL  for  last  control 

$04 

ctlOwner 

Long— Pointer  to  window  to  which  control  belongs 

$08 

ctlRect 

l?prtan(?lp— — Dffinps  X^xt  winHnw  hniinHarv  TPctiintAp 

a  1  ij^i^             u 1\>AL  Wll&lV/W  LA/UliUalj  iC^uLLiju\^ 

$10 

ctlFlag 

Byte — Define  text  display  and  storage  attributes 

$11 

ctlHlllte 

Byte— Controls  event  generation  for  control 

$12 

ctlValue 

Word— Text  size  field,  if  ctlData  contains  a  Poiruer 

$14 

ctlProc 

Long— statTextControl=$81000000 

$18 

ctlAction 

Long— Pointer  to  custom  procedure;  NIL  if  iione 

$1C 

ctlData 

Long— Reference  to  text  for  window 

$20 

ctlRefCon 

Long — Reserved  for  application  use 

$24 

ctlColor 

Long— Not  used;  must  be  set  to  0 

$28 

ctlJust 

Word— initial  justification  word 

$2A 

ctlReserved 

Block,  $0E  bytes— Not  used 

$38 

CtllD 

Long— Application-assigned  ID 

$3C 

ctlMoreFlags 

Word— Additional  control  flags 

$3E 

ct  IVerslon 

Word— Set  to  0 
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Valid  values  for  ctiFiag  are 


ctllnvis 

Reserved 

f SubstituteText 
f SubTextType 


bit? 
bits  2-6 
bit  1 

bit  0 


1  "invisible,  Divisible 
Must  be  set  to  0 

0=no  text  substitution  to  perform 
l=there  is  text  substitution  to  perform 
0=C  strings 
l=Pascal  strings 


Valid  values  for  ctiMoreFiags  are 

fCtlTarget  bit  15 

f  CtlCanBeTarget  bit  14 

fCtlWantsEvents  bit  13 

fCtlProcNotPtr  bit  12 

fCtlTellAboutSize  bit  11 

Reserved  bits  2-10 

Text  reference  bits  0-1 


Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  0 
Must  be  set  to  0 

Defines  type  of  text  reference  inctiData: 

00  -  text  reference  is  pointer 

01  -  text  reference  is  handle 

10  -  text  reference  is-  resource  ID 

11  -  invalid  value 

ctiHiiite        Specifies  whether  the  control  wants  to  receive  mouse  selection 
events.  The  values  for  ctiHiiite  are  as  follows: 

0     Events  will  be  generated  when  the  mouse  button  is  pressed  in  the 
control 

255  No  events  will  be  generated  when  the  mouse  button  is  pressed  in 
the  control 

ctivaiue         Contains  the  size  of  the  referenced  text  in  characters,  but  only  if  the 
text  reference  in  ctiData  is  a  pointer.  If  the  text  reference  is  either  a 
handle  or  a  resource  ID,  then  the  Control  Manager  can  extract  the 
length  from  the  handle. 
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ctijust  The  justification  word  is  passed  on  to  LETextBox2  (see 

Chapter  10,  "LineEdit  Tool  Set,"  in  Volume  1  of  the  Toolbox  Reference 
for  details  on  the  LETextBox2  tool  call),  and  is  used  to  set  the  initial 
justification  for  the  text  being  drawn.  Valid  values  for  cti  Just  are 

left  Justify      0      Text  is  left  justified  in  the  display  window 
center  Justify  1      Text  is  centered  in  the  display  window 
right  Justify    -1     Text  is  right  justified  in  the  display  window 
full  Justify      2      Text  is  fulJy  justified  (both  left  and  right)  in 

the  display  window 

Static  text  controls  do  not  support  color  tables.  To  display  text  of  different  color,  you 
must  embed  the  appropriate  commands  into  the  text  string  you  are  displaying.  See  the 
discussion  of  LETextBox2  in  Chapter  10,  "LineEdit  Tool  Set,"  in  Volume  1  of  the  Toolbox 
Reference  for  details  on  command  format  and  syntax. 
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TextEdit  control  record 

Figure  28-30  shows  the  format  of  the  control  record  for  TextEdit  controls. 
■   Figure  28-30   TextEdit  control  record 


$00 


$04 


$08 


$10 
$11 
$12 

$14 


$18 


$1C 


$20 


$24 


$28 


$2C 


ctiNext        -  Long— Handle  to  next  control;  NE  for  last  contrd 


ctlOwner 


Long— Pointer  to  window  to  which  conlrd  belongs 


ctiReot  :  Rectangle— Defines  control  boundary  rectangle 


ctlFlag 


ctlHlllte 


ct lvalue 


ctlProc 


ctlAction  — 


ctlData 


—         ctlRefCon  — 


textFiags       -  Long— TextEdit  bit  flags 


textLength      -  Long— Length  of tcxt 


continued 


Byte— Defines  control  visibility 
Byte— Not  used;  must  be  set  to  0 

Word— Contains  the  last  reported  TextEdit  error  code 
Long— editTextCQiitrol=$85000000 


Long— Pointer  to  custom  procedure;  NIL  if  none 


Long— Pointer  to  filter  procedure 


Long— Reserved  for  application  use 


cticoior       -  Long— Reference  to  the  color  table  for  the  control 


28-128  Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


$30 
$38 

$3C 
$3E 
$40 

$48 

$4C 
$58 


continued 


biocicList        ■  Textlist— Cached  link  into  TextBlock  list 


ctllD 

ct IMoreFlags 

ctlVersion 

Long— Application-assigned  E) 

Word— Additional  control  flags 
Word— Set  to  0 


viewRect 


Rectangle— Boundary  rectangle  for  text 
totaiHeight     -  Long— Height,  in  pixcls,  oftcxt 
linesuper        '■  SupaHandle— Cached  link  into  text  lines 
styleSuper        :  SuperHandle— Cached  link  into  style  list 

Long— Handle  to  array  of  TESty  le  records 


$64 

styleLlst 

$68 

ruler List 

$6C 

llneAtEndFlag 

$6E 

select lonStart 

$72 

selectlonEnd 

continued 

Long— HarxUe  to  array  of  TERuler  records 
Wad— Line  break  flag 

Long— Starting  text  offset  for  current  selection 
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$76 
$78 
$7A 

$7E 
$80 

$8C 

$90 
$92 

$96 

$9A 

$9E 
$0A 


—    selectionActlve  — 


—  selectionState 


continued 


—         caretTlme  — 


—  nullStyleActlve 


Word— Flag  indicating  whaher  current  selection  is  active 
Word— State  information  about  current  selection 

Long— Blink  interval  for  caret,  in  system  ticks 

Word— Flag  indicating  whether  null  style  is  active 


nuiistyie        '■  TEStyle — Null  style  definition 


—      topTextOf fset  — 


—  topTextVPos 


—      vertScrollBar  — 


$A4 


$A8 


vertScrollPos  — 


vertScrollMax 


—  vertScrollAmount 


horzScrollBar  — 


—  horzScrollPos 


horzScrollMax 


continued 


Long— Offset  to  top  line  of  displayed  text 

Word— Position  of  display  window  into  text,  in  pixels 

Long— Handle  to  vertical  saoll  bar  control  record 

Long— Current  pcsition  of  vertical  saoll  bar 

Long— Maximum  allowable  vertical  saoll 
Word— Number  of  pixels  to  saoll  cm  each  click 
Long— Currently  not  suppmed 

Long— Currently  not  supported 

Long— Currently  not  supported 
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$AC 


—  horzScrollAmount  — 


$AE  _ 

—  growBoxHandle 


$B2 

$B6 

$BA 
$BC 
$B£ 

$00 
$C4 
$C8 

$CC 

$IM 
$D6 


—  maxlmumLlnes 


—    maxCharsPerLine  — 


continued 


maxlmumChars  — 


maxlmumHeight  — 


—  textDrawMode 


—     wordBreakHook  — 


Word— Currently  not  supported 
Long— Handle  of  size  box  control  record 

Long— Maximum  number  of  characters  allowed  in  text 

Long— Currently  not  supported 

WcM'd— Cun-ently  not  supported 
Wad— Currently  not  supported 
Word— QuickDraw  II  drawing  mode  for  text 


Long— Pointer  to  word  break  hook  routine 
wordwrapHook     -]  Long— Pointer  to  word  wrap  hook  routine 
keyFiiter  Long-^olnter  to  keystroke  filter  routinc 


theFiiterRect      '■  Rectangle-^ectangle  for  generic  filter  proccdure 


thoBufferVPos 

theBufferHPos 

continued 


Word— Vertical  component  of  current  position 
Word— Horizontal  component  of  cunent  position 
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$D8 
$E6 

$EA 
$EC 
$EE 

$F6 


continued 


theKeyReoord      :  KeyRccord— Parameters  for  keystroke  filter  routine 


cachedSelcOffset  — 


—     cachedSelcVPos  — 


cachedSelcHPos  — 


Long— Cached  selection  text  offset 

Word— Vertical  component  of  cached  buffer  position 
Word— Horizontal  component  of  cached  buffer  position 


$FA 
$FC 

$100 
$102 


—  mouseKind 


mouseRect        \  Rectangle— Boundary  rectangle  for  multiclick  mouse  Commands 


mouseTime 


lastClick  - 


savedHPos 


anchorPolnt  — 


Long— Time  of  last  mouse  click 
Word— Kind  of  mouse  click  last  performed 
Long— Location  of  last  mouse  dick 
Word— Cached  horizontal  character  position 
Long— Starting  point  of  current  selection 


Valid  values  for  ctiFiag  are 

ctiinvis  bit  7  l«=invisible,  0=visible 

Reserved  bits  0-6      Must  be  set  to  0 
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Valid  values  for  textFiags  are 


fNotControl  bit  31 

f  SingleFormat  bit  30 

f  SingleStyle  bit  29 

fNoWordWrap  bit  28 

fNoScroll  bit  27 

fReadOnly  bit  26 

f  SmartCutPaste  bit  25 

f  TabSwitch  bit  24 

fDrawBounds  bit  23 

fColorHilight  bit  22 

f  GrowRuler  bit  21 


Must  be  set  to  0 
Must  be  set  to  1 

Indicates  the  style  options  available  to  the  user 
1  -  Allow  only  one  style  in  the  text 

0  -  Do  not  restrict  the  number  of  styles  in  the 
text 

Indicates  TextEdit  word  wrap  behavior 

1  -  Do  not  word  wrap  the  text;  only  break  lines 
on  CR  ($0D)  characters 

0  -  Perform  word  wrap  to  fit  the  ruler 
Controls  user  access  to  scrolling 

1  -  Do  not  allow  either  manual  or  auto-saolling 

0  -  Scrolling  permitted 

Restricts  the  text  in  the  window  to  read-only 
operations  (copying  from  the  window  will  still 
be  allowed) 

1  -  No  editing  allowed 

0  -  Editing  permitted 

Controls  TextEdit  support  for  smart  cut  and 
paste  (see  Chapter  49,  "TextEdit,"  for  details 
on  smart  cut  and  paste  support) 

1  -  Use  smart  cut  and  paste 

0  -  Do  not  use  smart  cut  and  paste 
Defines  behavior  of  the  Tab  key  (see 
Chapter  49,  "TextEdit,"  for  details) 

1  -  Tab  to  next  control  in  the  window 

0  -  Tab  inserted  in  TextEdit  document 
Indicates  whether  TextEdit  will  draw  a  box 
around  the  edit  window,  just  inside  ctiRect 
(the  pen  for  this  rectangle  is  2  pixels  wide  and  1 
pbcel  high) 

1  -  Draw  rectangle 

0  -  Do  not  draw  rectangle 
Must  be  set  to  0. 

Indicates  whether  TextEdit  will  resize  the  ruler 
in  response  to  the  user  resizing  the  edit  window. 
If  set  to  1,  TextEdit  will  automatically  adjust 
the  right  margin  value  for  the  ruler 

1  -  Resize  the  ruler 

0  -  Do  not  resize  the  ruler 
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fDisableSelection 


fDrawInactiveSelection 

bit  19 


Reserved 
textLength 

blockList 


bit  20         Controls  whether  user  can  select  text 
1  -  User  cannot  select  text 

0  -  User  can  select  text 

Controls  how  inactive  selected  text  is  displayed 

1  -  TextEdit  draws  a  box  around  inactive 
selections 

0  -  TextEdit  does  not  display  inactive 
selections 
bits  0-18     Must  be  set  to  0 

Number  of  bytes  of  text  in  the  record.  Your  program  must  not  modify 
this  field. 

Cached  link  into  the  linked  list  of  TextBiock  stmctures,  which 
contain  the  actual  text  for  the  record.  The  actual  TextList  structure 
resides  here.  Your  program  must  not  modify  this  field. 
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Valid  values  for  ctiMoreFiags  are 


fCtlTarget 

fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcNotPtr 

fTellAboutSize 


fCtllsMultiPart 

Reserved 

Color  table  reference 


Style  reference 


bit  15 

bit  14 

bit  13 

bit  12 

bit  11 


bit  10 
bits  4-9 
bits  2-3 


bits  0-1 


Must  be  set  to  0 
Must  be  set  to  1 
Must  be  set  to  1 
Must  be  set  to  1 

If  set  to  1,  a  size  box  will  be  created  in  the 
lower-right  comer  of  the  window.  Whenever  the 
control  window  is  resized,  the  edit  text  will  be 
resized  and  redrawn. 

Must  be  set  to  1  | 
Must  be  set  to  0 

Defines  type  of  reference  incticoior(ifitis 
not  NIL).  The  color  table  for  a  TextEdit  control 
(TECoiorTabie)  is  described  in 
Chapter  49,  TextEdit,"  later  in  this  book 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 

Defines  type  of  style  reference  in  styieRef . 
The  format  for  a  TextEdit  style  descriptor  is 
described  in  Chapter  49,  "TextEdit,"  later  in  this 
book 

00  -  style  reference  is  pointer 

01  -  style  reference  is  handle 

10  -  style  reference  is  resource  ID 

11  -  invalid  value 


A  Important 


Do  not  set  f  TeiiAboutsize  to  1  unless  the  control  also  has  a 
vertical  scroll  bar.  a 


viewRect 

totalHeight 
lineSuper 


Boundary  rectangle  for  the  text,  within  the  rectangle  defined  in 
boundsRect,  which  surrounds  the  entire  record,  including  its 
associated  scroll  bars  and  outline. 

Total  height  of  the  text  in  the  TextEdit  record,  in  pixels. 

Cached  link  into  the  linked  list  of  SuperBiock  suiictures  that  define 
the  text  lines  in  the  record. 
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styiesuper      Cached  link  into  the  linked  list  of  SuperBiock  structures  that  define 
the  styles  for  the  record. 

styieList  Handle  to  array  of  TEStyie  structures,  containing  style  information 
for  the  record.  The  array  is  terminated  with  a  long  set  to  $FFFFFFFF. 

ruierList  Handle  to  array  of  TERuier  structures,  defining  the  format  mlers  for 
the  record.  Note  that  only  the  first  ruler  is  currendy  used  by  TextEdit. 
The  array  is  terminated  with  a  long  set  to  $FFFFFFFF. 

lineAtEndFiag  Indicates  whether  the  last  character  was  a  line  break.  If  so,  this  field  is 
set  to  $FFFF. 

select ionStart 

Starting  text  offset  for  the  current  selection.  Must  always  be  less  than 
selectionEnd. 

seiectionEnd   Ending  text  offset  for  the  current  selection.Must  always  be  greater 
than  selectionStart. 

selectionActive 

Indicates  whether  the  current  selection  (defined  by 
selectionStart  and  selectionEnd)  is  active: 

$0000  Active 
$FFFF  Inactive 

seiectionstate      Contains  state  information  about  the  current  selection  range: 

$0000  Off  screen 

$FFFF  On  screen 

caretTime        Blink  interrval  for  caret,  expressed  in  system  ticks. 

nullStyleActive 

Indicates  whether  the  null  style  is  active  for  the  current  selection: 

$0000  Do  not  use  null  style  when  inserting  text 

$FFFF  Use  null  style  when  inserting  text 

nuiistyie        TEStyie  Structure  defining  the  null  style.  This  may  be  the  default 
style  for  newly  inserted  text,  depending  upon  the  value  of 
nullStyleActive. 

topTextof  f  set  Text  offset  into  the  record  corresponding  to  the  top  line  displayed  on 
the  screen. 
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topTextvpos     Difference.in  pixels,  between  the  topmost  vertical  scroll  position 
(corresponding  to  the  top  of  the  vertical  saoU  bar)  and  the  top  line 
currently  displayed  on  the  screen.  This  is,  essentially,  the  vertical 
position  of  the  display  window  in  the  text  for  the  record. 

vertScroiiBar  Handle  to  the  vertical  saoli  bar  control  record. 

vertscroiiPos  Current  position  of  the  vertical  scroll  bar,  in  units  defined  by 
vertScrollAmount, 

♦  Note:  that  while  TextEdit  supports  vertScroiiPos  as  a  long,  standard  Apple  IIGS 
scroll  bars  support  only  the  low-order  word.  This  leads  to  unpredictable  scroll  bar 
behavior  when  editing  large  documents. 

vertScroiiMax  Maximum  allowable  vertical  scroll,  in  units  defined  by 
vertScrollAmount. 

vertScrollAmount 

Number  of  pixels  to  scroll  on  each  vertical  arrow  click. 

horzScroiiBar  Handle  to  the  horizontal  scroll  bar  control  record.  Currently  not 
supported 

horzScroiiPos  Current  position  of  the  horizontal  scroll  bar,  in  units  defined  by 
horzScroiiAmount,  Currently  not  supported 

horzScroiiMax  Maximum  allowable  horizontal  scroll,  in  units  defined  by 
horzScroiiAmount.  Currently  not  supported 

horzScroiiAmount 

Number  of  pixels  to  scroll  on  each  horizontal  arrow  click.  Currently  not 
supported. 

growBoxHandie  Handle  of  size  box  control  record, 
maximumchars    Maximum  number  of  charaaers  allowed  in  the  text. 
maximumLines    Maximum  number  of  lines  allowed  in  the  text.  Currently  not  supported. 

maxCharsPerLine 

Currendy  not  supported. 

maximumHeight  Maximum  text  height,  in  pixels.  This  value  allows  applications  to  easily 
constrain  text  to  a  display  window  of  a  known  height.  Currendy  not 
supported. 
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textDrawMode    QuickDraw  11  drawing  mode  for  the  text.  See 

Chapter  16,  "QuickDraw  II,"  in  the  Toolbox  Reference  for  more 
information  on  QuickDraw  11  drawing  modes. 

wordBreakHook  Pointer  to  the  routine  that  handles  word  breaks.  See 

Chapter  49,  "TextEdit,"  for  information  about  word  break  routines. 
Your  program  may  modify  this  field. 

wordWrapHook   Pointer  to  the  routine  that  handles  word  wrap.  See 

Chapter  49,  "TextEdit,"  for  information  about  word  wrap  routines. 
Your  program  may  modify  this  field. 

keyFiiter  Pointer  to  the  keystroke  filter  routine.  See  Chapter  49,  "TextEdit," 
for  information  about  keystroke  filter  routines.  Your  program  may 
modify  this  field. 

theFiiterRect  Defines  a  rectangle  used  by  the  generic  filter  procedure  for  some  of  its 
routines.  See  Chapter  49,  "TextEdit,"  for  information  about  generic 
filter  procedures  and  their  routines.  Your  program  may  modify  this 
field. 

theBuf  f  ervpos  Vertical  component  of  the  current  position  of  the  buffer  within  the 
port  for  the  TextEdit  record,  expressed  in  the  local  coordinates 
appropriate  for  that  port.  This  value  is  used  by  some  generic  filter 
procedure  routines.  See  Chapter  49,  "TextEdit,"  for  information 
about  generic  filter  procedures  and  their  routines.  Your  program  may 
modify  this  field. 

theBuf  ferHPos  Horizontal  component  of  the  current  position  of  the  buffer  within  the 
port  for  the  TextEdit  record,  expressed  in  the  local  coordinates 
appropriate  for  that  port.  This  value  is  used  by  some  generic  filter 
procedure  routines.  See  Chapter  49,  "TextEdit,"  for  information 
about  generic  filter  procedures  and  their  routines.  Your  program  may 
modify  this  field. 

theKeyRecord   Parameter  block,  in  KeyRecord  format,  for  the  keystroke  filter 
routine.  Your  program  may  modify  this  field. 

C3ch©dS©lc0f  f s©t 

Cached  selecUon  text  offset.  If  this  field  is  set  to  $FFFFFFFF,  then  the 
cache  is  invalid  and  will  be  recalculated  when  appropriate. 

cachedSelcVPos 

Vertical  component  of  the  cached  buffer  position,  expressed  in  local 
coordinates  for  the  output  port. 
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cachedSelcHPos 

Horizontal  component  of  the  cached  buffer  position,  expressed  in 
local  coordinates  for  the  output  port. 

mouseRect        Boundary  rectangle  for  multiclick  mouse  commands.  If  the  user  clicks 
the  mouse  more  than  once  within  the  region  defined  by  this  rectangle 
within  the  time  period  defined  for  multiclicks,  then  TextEdit 
interprets  those  clicks  as  multiclick  sequences  (double-  or  triple- 
clicks).  The  user  sets  the  time  period  with  the  Control  Panel. 

mouseTime        System  tickcount  when  the  user  last  released  the  mouse  button. 

itiouseKind        Type  of  last  mouse  click: 


0 
1 
2 

lastClick 
savedHPos 


anchorPoint 


Single  click 

Double-click 

Triple-click 

Location  of  last  user  mouse  click. 

Cached  horizontal  character  position.  TextEdit  uses  this  value  to 
manage  where  it  should  display  the  caret  on  a  line  when  the  user 
presses  the  up  or  down  arrow. 

Defines  the  character  from  which  the  user  began  to  select  text  for  the 
current  selection.  When  TextEdit  expands  the  current  selection  (as  a 
result  of  user  keyboard  or  mouse  commands,  or  at  the  direction  of  a 
custom  keystroke  filter  procedure),  it  always  does  so  from  die 

anchorPoint,  not  selectionStart  or  selectionEnd. 
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Chapter  29  Desk  Manager  Update 


This  chapter  documents  new  features  of  the  Desk  Manager.  The 
complete  reference  to  the  Desk  Manager  is  in  Volume  1,  Chapter  5  of  the 
Apple  IIGS  Toolbox  Reference. 
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New  features  in  the  Desk  Manager 

It  is  now  possible  for  a  new  desk  accessory  (NDA)  to  be  a  modal  dialog  box.  When  an 
NDA  is  opened,  it  returns  a  pointer  to  its  window.  The  Desk  Manager  saves  this  pointer 
and  marks  the  NDA  open.  The  current  version  of  the  Desk  Manager  checks  the  returned 
window  pointer,  and  if  its  value  is  0  (if  it  is  a  null  pointer)  then  the  Desk  Manager  does  not 
mark  the  NDA  open.  Subsequent  attempts  to  open  the  NDA  simply  select  the  open 
window  until  the  NDA  is  dosed.  A  programmer  can  therefore  write  an  NDA  that  opens  a 
modal  dialog  box  when  chosen.  When  the  dialog  box  is  dismissed,  the  NDA  can  be  chosen 
again  without  having  been  explicidy  closed. 


Scrollable  CDA  menu 

The  classic  desk  accessory  (CDA)  menu  is  now  saollable.  Previously,  the  menu  held  a 
maximum  of  13  entries  in  a  fixed  display.  Now,  up  to  249  desk  accessories  can  be  installed 
and  displayed. 

Scrolling  takes  place  only  on  systems  with  14  or  more  CDAs  installed.  When  the  menu  is 
scrollable,  the  system  displays  a  more  message  at  each  scrollable  end  of  the  menu.  That  is, 
if  there  are  additional  items  above  those  currentiy  visible,  the  more  message  appears  at 
the  top  of  the  menu.  Similarly,  if  there  are  more  items  below  those  currendy  visible,  a  more 
message  appears  at  the  bottom  of  the  menu.  Messages  may  be  placed  at  both  the  top  and 
bottom  of  the  menu,  if  appropriate. 

The  new  menu  behaves  somewhat  differently  from  die  old  one.  When  the  user  returns  to 
the  CDA  menu  from  an  accessory,  die  name  of  that  accessory  is  highlighted  (previously, 
the  Control  Panel  entry  was  highlighted).  In  addition,  the  user  can  no  longer  wrap  from  the 
bottom  of  the  menu  to  the  top,  or  vice  versa. 
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The  valid  keystrokes  for  the  CDA  menu  are: 


Keystroke 


Effect 


Up  Arrow 


Moves  selection  box  up  one  entry  in  the  menu;  no  effect  if  at 
the  top  of  the  menu 


Command-Up  Arrow 


Moves  selection  box  up  one  page  in  the  menu;  no  effect  if  at 
the  top  of  the  menu 


Down  Arrow 


Moves  selection  box  down  one  entry  in  the  menu;  no  effect  if 
at  the  bottom  of  the  menu 


Command-Down  Arrow     Moves  selection  box  down  one  page  in  the  menu;  no  effect  if 

at  the  bottom  of  the  menu 


Run  queue 

The  run  queue  allows  you  to  install  tasks  (run  items)  that  need  to  be  called  periodically. 
You  establish  the  periodicity  of  the  call  by  managing  a  field  in  the  run  item  header.  The 
Desk  Manager  has  two  new  system  calls,  AddToRunQ  and  RemoveFromRunQ,  that  allow 
you  to  install  and  remove  mn  items  from  the  queue. 

The  system  examines  the  run  queue  at  system  task  time,  when  the  system  is  guaranteed  to 
be  free  and  all  tools  are  available.  For  each  run  item  in  the  queue,  the  system  adjusts  the 
period  header  field.  If  the  specified  time  period  has  elapsed,  the  system  then  calls  the 
run  item. 

The  run  queue  is  quite  similar  to  the  heartbeat  queue,  and  should  be  used  in  its  place. 


Esc 


Enter  or  Return 


Selects  the  highlighted  item 
Selects  Quit 
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Each  run  item  must  be  preceded  by  a  header  formatted  as  follows: 


$00 

Reserved 

Long— Used  by  system  as  link  to  next  run  queue  item 

$04 

period 

Wad  (unsigned)— Period  to  wait,  in  ticks 

$06 

signature 

Word— Header  signature,  to  ensure  integrity— set  to  $A55A 

$08 

Reserved 

Long— Used  by  system  to  know  when  item  was  last  executed 

period 


Specifies  the  minimum  number  of  system  ticks  that  are  to  elapse 
between  run  item  executions.  Each  system  tick  represents  l/60th  of  a 
second.  A  value  of  0  indicates  that  the  item  is  to  be  called  as  often  as 
possible.  A  value  of  $FFFF  indicates  that  the  item  should  never  be 
called.  While  the  run  queue  supports  call  frequencies  up  to 
approximately  60  per  second,  the  timing  is  less  accurate  for  periods 
shorter  than  one  second. 


A  Important 


Run  item  code  must  reset  the  period  field  before  returning  control  to 
the  system.  Failure  to  do  so  will  result  in  a  period  of  0,  which  will 
cause  the  item  to  be  called  constantly,  a 


signature        Used  by  the  system  to  ensure  that  the  header  is  well  formed.  The  value 
of  this  field  must  be  $A55A. 

The  entry  point  must  immediately  follow  the  header.  Run  items  need  not  check  the  busy 
flag,  since  the  system  is  guaranteed  to  be  free  before  any  run  item  is  invoked.  However, 
run  items  must  be  careful  to  save  and  restore  the  operating  environment,  since  they  may 
be  invoked  from  TaskMaster,  as  well  as  from  an  application.  You  should  also  be  careful  to 
either  unload  your  run  items  at  application  termination,  or  ensure  that  remaining  items  are 
not  purgeable. 

While  the  run  queue  and  heartbeat  queue  (see  Chapter  14,  "Miscellaneous  Tool  Set,"  in 
Volume  1  of  the  Toolbox  Reference  for  information  about  the  heartbeat  queue)  are 
somewhat  similar,  there  are  some  significant  differences.  First,  the  run  item  header  has  an 
additional  field  (the  second  Reserved  field).  Second,  the  system  does  not  remove  items 
from  the  run  queue  when  their  pe  r i  od  reaches  0. 
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Run  queue  example 

Following  is  an  example  nin  item,  which  beeps  the  speaker  every  15  minutes. 
;  RunQ  example  task  that  beeps  every  15  minutes. 

;  It  is  provided  in  MPWIIgs  assembler  format.  The  first  portion  is  the 
;  task  header. 

BeepHdr  Record 


period 


ds.L  1 
dc.W  $D2F0 
dc.W  $A55A 
dc.L  0 


reserve  1  long  for  link  to  next  runQ  entry 
number  of  60th  of  a  sec  (54000=15  minutes) 
signature  used  to  test  for  queue  integrity 
used  by  desk  mgr  to  keep  track  of  the  time 


EndR 


Now  the 


actual  code  of 


the  task  goes  here. 


BeepTask 


Proc 


with  BeepHdr 


SysBeep 


beep  the  speaker  once 


Ida  #$D2F0  ; 
sta  >period  ; 


rtl 


and  now  recharge  the  period  for  next  call 
NOTE: Use  long  addressing:  DataBank  unknown 
and  to  exit  use  an  RTL 


EndP 


The  following  code  installs  the  above  item  into  the  run  queue 


PushLong  #BeepHdr 
Idx  #$1F05 
jsl  >$E10000 
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New  Desk  Manager  calls 

The  following  new  Desk  Manager  calls  support  the  run  queue  and  desk  accessory  removal. 
AddToRunQ  $1F05 

Adds  the  specified  routine  to  the  head  of  the  run  queue. 

Parameters 

Stack  before  call 


Previous  contents 


runltemPtr 


Long— Pointer  to  run  item  to  add 
<— SP 


Stack  after  call 


Prmous  contents 


Errors 
C 


<— SP 
None 

extern  pascal  void  AddToRunQ (runltemPtr) ; 
Pointer  runltemPtr; 
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RemoveFromRunQ  $2005 

Removes  the  specified  run  item  from  the  mn  queue. 

Parameters 

Stack  before  call 


PretHous  contents 


-    ninltemPtr  - 


Stack  after  call 


Long— Pointer  to  run  item  to  remove 
<— SP 


Previous  contents 


Errors 
C 


<— SP 
None 

extern  pascal  void  RemoveFromRunQ (runltemPtr) ; 
Pointer  runltemPtr; 
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RemoveCDA  $2105 

Removes  the  specified  CDA  from  the  Desk  Manager  CDA  list.  This  routine  does  not 
dispose  of  the  memory  used  by  the  DA. 

This  routine  is  the  complement  of  instaiiCDA  (which  is  described  in 
Chapter  5,  "Desk  Manager,"  in  the  Toolbox  Reference). 

You  should  be  very  careful  before  issuing  this  call.  Users  generally  install  desk  accessories 
for  their  own  use;  you  should  not  spontaneously  remove  them  from  the  system.  Also,  note 
that  many  desk  accessories  install  other  custom  code  (in  the  run  queue,  for  example);  you 
should  not  remove  them  unless  you  know  that  the  other  code  has  been  removed,  as  well. 

Parameters 

Stack  before  call 


Previous  contents 


idHandle 


Stack  after  call 


Long— Handle  to  CDA  header 
<— SP 


Previous  contents 


Errors 


$0510 


<— SP 
DaNotFound 


Specified  desk  accessory  not 
found. 


extern  pascal  void  RemoveCDA ( idHandle ) ; 
Handle  idHandle; 
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RemoveNDA  $2205 

Removes  the  specified  NDA  from  the  Desk  Manager  NDA  list.  This  routine  does  not 
dispose  of  the  memory  used  by  the  DA. 

This  routine  is  the  complement  of  instaiiNDA  (which  is  described  in 
Chapter  5,  "Deslc  Manager,"  in  the  Toolbox  Reference). 

This  call  does  not  rebuild  the  Apple  menu.  Your  application  must  rebuild  the  menu  by 
issuing  the  FixAppleMenu  tool  call. 

Parameters 

Stack  before  call 


Previous  contents 


idHandle 


Long— Handle  to  NDA  header 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$0510 


<— SP 
DaNotFound 


Specified  desk  accessory  not 
found. 


extern  pascal  void  RemoveNDA ( idHandle ) ; 
Handle  idHandle; 
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Chapter  30  Dialog  Manager  Update 


This  chapter  documents  new  features  of  the  Dialog  Manager.  The 
complete  reference  to  the  Dialog  Manager  is  in  Volume  1,  Chapter  6  of 
the  Apple  IIGS  Toolbox  Reference. 
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Error  corrections 

This  section  explains  changes  that  have  been  made  to  the  Dialog  Manager's 
documentation  in  the  Apple  IIGS  Toolbox  Reference. 

m  The  documentation  for  setDitemType  on  page  6-82  of  the  Toolbox  Reference  says 
that  the  call  is  used  to  change  a  dialog  item  to  a  different  type.  In  faa, 
SetDitemType  should  be  used  only  to  change  the  state  of  an  item  from  enabled  to 
disabled  or  vice  versa. 

■  The  Dialog  Manager  does  not  support  dialog  item  type  values  of  picitem  or 
iconitem,  contrary  to  what  the  Toolbox  Reference  stites  in  Table  6-3  on  page  6-12. 
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Chapter  31  Event  Manager  Update 


This  chapter  documents  new  features  of  the  Event  Manager.  The 
complete  reference  to  the  Event  Manager  is  in  Volume  1,  Chapter  7  of  the 
Apple  DCS  Toolbox  Reference. 
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New  features  in  Event  Manager 

The  following  sections  discuss  new  features  of  the  Event  Manager. 


Journaling  changes 

Previously,  journaling  did  not  capture  operations  that  involved  the  ReadMouse 
Miscellaneous  Tool  Set  call,  because  that  call  did  not  support  journaling.  As  discussed  in 
Chapter  39,  "Miscellaneous  Tool  Set  Update,"  in  this  book,  ReadMouse  has  been  changed 
to  support  journaling.  As  a  result,  journaling  routines  must  now  handle  a  new  journal  code. 

When  an  application  calls  ReadMouse,  and  journaling  is  on,  your  journaling  routine  will  be 
called  with  a  journal  code  of  6  and  resultPtrm)!  point  to  a  6-byte  record  containing 
ReadMouse  data.  This  record  has  the  following  format: 


$00 

—        StatusMode  — 

Word— Mouse  status/mode  bytes 

$02 

—         yLocatlon  — 

Word— Absolute  y  location  of  pointing  device 

$04 

—         xLocatlon  — 

Word— Absolute  x  location  of  pointing  device 

StatusMode      Mouse  status  and  mode  bytes,  as  described  on  pages  14-35  and  14-36 
of  the  Toolbox  Reference. 
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Keyboard  input  changes 

The  system  now  processes  keyboard  input  through  a  translation  routine,  allowing  Apple 
IIGS  and  Macintosh®  keystrokes  to  match.  The  translation  routine  uses  a  resource-based 
keystroke  translation  table,  which  is  identified  by  a  unique  resource  ID.  You  can  assign 
other  tables  to  suit  the  needs  of  a  particular  language  or  keyboard.  There  are  new  Event 
Manager  calls  to  read  or  write  the  current  keyboard  translation  table  resource  ID. 

Note  that  the  system  translates  keystrokes  before  performing  dead  key  replacements.  To 
HKxlify  dead-key  sequences  you  may  find  it  easier  to  modify  the  appropriate 
transTabie  entry,  since  that  table  is  more  straightforward  than  the  deadKeyTable 
and  replacementTable. 

The  keystroke  translation  table  must  be  formatted  as  follows: 

$000  I  I 

:       transTabie        \  256  Bytcs— Keystroke  translation  array 


$100  I I 

:      deadKeyTable      '■  XX  Bytes— Dead-key  Validation  array 


$100+xx  I 

:    replacementTable    '■  yy  Bytcs— Dead-key  replacement  array 

i  i 


transTabie      This  is  a  packed  array  of  bytes  used  to  map  the  ASCII  codes  produced 
by  the  keyboard  into  the  character  value  to  be  generated.  Each  cell  in 
the  array  direcdy  corresponds  to  the  ASCII  code  that  is  equivalent  to 
the  cell  offset.  For  example,  the  transTabie  cell  at  offset  $0D  (13 
decimal)  contains  the  character  replacement  value  for  keyboard  code 
$0D,  which,  for  a  straight  ASCII  translation  table,  is  a  Return  character 
(CR).  The  transTabie  cells  from  128  to  255  ($80  to  $FF)  contain 
values  for  Option-key  sequences  (such  as  Option-S). 
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deadKey  Table   This  table  contains  entries  used  to  validate  dead  keys.  Dead  key 

refers  to  keystrokes  used  to  introduce  multikey  sequences  that  result 
in  single  characters.  For  example,  pressing  Option-u  followed  by  e 
yields  an  e  with  an  umlaut.  There  is  one  entry  in  deadKeyTabie  for 
each  defined  dead  key.  The  last  entry.must  be  set  to  $0000.  Each  entry 
must  be  formatted  as  follows; 


Byte— Character  code  for  dead  key 

Byte— Offset  from  deadKeyTabie  rnto  replacementTable 


deadKey 
offset 


deadKey  Contains  the  character  code  for  the  dead  key.  The  system  uses 

this  value  to  check  for  user  input  of  a  dead  key.  The  system 
compares  this  value  with  the  first  user  keystroke. 

offset  Byte  offset  from  beginning  of  deadKeyTabie  into  relevant 

subarray  in  replacementTable,  divided  by  2.  The  system 
uses  this  value  to  access  the  valid  replacement  values  for  the 
dead  key  in  question. 

replacementTable 

This  table  contains  the  valid  replacement  values  for  each  dead  key 
combination.  This  table  is  made  up  of  a  series  of  variable-length 
subarrays,  each  relevant  to  a  particular  dead  key.  The  last  entry  in  each 
sub-array  must  be  set  to  $0000.  Each  entry  in  the 
replacementTable  must  be  formatted  as  follows: 


scanKey 


replaceValue 


Byte— Charaaer  code  for  dead  key  combination 
Byte— Result  charaaer  code  for  dead  key  combinaticm 


scanKey  Contains  a  valid  character  code  for  dead  key  replacement.  The 

system  uses  this  field  to  determine  whether  the  user  entered  a 
valid  dead  key  combination.  The  system  compares  this  value 
with  the  second  user  keystroke. 

replaceValue    Contains  the  replacement  value  for  the  character  specified  in 
scanKey  for  this  entry.  The  system  delivers  this  value  as  the 
replacement  for  a  valid  dead  key  combination. 
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New  Event  Manager  calls 

There  are  several  new  Event  Manager  calls,  many  concerning  the  new  keyboard  translation 
feature. 


GetKeyTranslation  $1B06 

Returns  the  identifier  for  the  currently  selected  keystroke  translation  table.  Before  setting 
a  new  translation  table,  your  application  should  read  and  save  the  current  identifier.  When 
your  application  terminates,  it  should  restore  the  previous  keystroke  translation  table. 
Use  the  setKeyTransiation  call  to  modify  the  current  identifier. 

Parameters 

Stack  before  call 

Previous  contend 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


kTransID 


Word— Keyboard  translation  identifier  ($0000  to  $OOFF) 


<— SP 


Errors 


None 


C 


extern  pascal  Word  GetKeyTranslation {) ; 
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SetAutoKeyLimit  $1A06 

Controls  how  repeated  keystrokes  are  inserted  into  the  event  queue.  The  default  value  for 
the  limit  is  0,  which  specifies  that  auto-key  events  are  inserted  only  if  no  other  events  are 
aheady  in  the  queue.  The  newLimit  parameter  determines  how  many  auto-key  events  must 
be  in  the  event  queue  before  Post  Event  ceases  to  add  them.  For  example,  if  newLimit  is 
0,  then  the  default  condition  is  maintained:  PostEvent  will  not  add  auto-key  events 
unless  the  queue  is  empty.  However,  if  newLimit  is  5,  then  PostEvent  will  add  five  auto- 
key  events  to  the  queue  before  it  reverts  to  the  rule  that  no  more  auto-key  events  are  to 
be  posted. 

Parameters 

Stack  before  call 


Previous  contents 


newLimit 


Word— Limit  for  inserted  auto-key  events 
<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 


<— SP 
None 

extern  pascal  void  SetAutoKey Limit (newLimit)  ; 
Word  newLimit; 
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SetKeyTranslation  $1C06 


Sets  a  new  keystroke  translation  table.  Once  set,  the  selected  keystroke  translation  table 
stays  in  effect  until  this  call  is  issued  again,  irrespective  of  application  termination, 
system  resets,  or  system  power  off.  Before  setting  a  new  value  for  the  keystroke 
translation  table,  your  application  should  read  and  save  the  current  value,  using  the 
GetKeyTransiation  tool  call.  Your  application  should  then  restore  that  previous  value 
when  it  is  finished. 

The  system  reads  keystroke  translation  tables  from  resources  of  type  $8021  and  ID 
$0FFF06xx,  where  xx  derives  from  die  low-order  byte  of  the  kTransID  parameter. 

This  call  uses  the  current  resource  search  path  to  find  the  specified  resource.  If  you  want 
your  translation  to  stay  in  effect  after  your  application  has  terminated,  you  must  place 
the  translation  table  resource  in  the  system  resource  file. 

If  the  system  cannot  find  a  resource  corresponding  to  the  value  specified  in  kTransID,  the 
keyboard  defaults  to  the  standard  keystroke  translation  table  ($(X)FF). 

Parameters 

Stack  before  call 

Prmous  contents 


kTransID 


Word— Keystroke  translation  table  identifier  (low-order  byte) 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


None 


c 


extern  pascal  void  SetKeyTranslation (kTransID) ; 


Word 


kTransID; 


kTransID 


The  following  are  standard  values  for  kTransID. 


$0000     Use  old-style  Apple  IIGS  keyboard  mapping 

$OOFF     Use  standard  keyboard  remapping  (makes  Apple  IIGS  key 


sequences  match  Macintosh) 
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Chapter  32  Font  Manager  Update 


This  chapter  documents  new  features  of  the  Font  Manager.  The  complete 
reference  to  the  Font  Manager  is  in  Volume  1,  Chapter  8  of  the 
Apple  BGS  Toolbox  Reference. 
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New  features  in  the  Font  Manager 

■  The  current  version  of  the  Font  Manager  incorporates  several  changes.  In  previous 
versions,  FMStartup  opened  each  font  file  in  the  FONTS  folder,  and  constructed  lists 
of  information  for  all  available  fonts.  These  lists  contained  font  IDs,  font  names,  and 
so  forth  for  every  font  in  the  FONTS  folder.  The  present  version  of  the  Font  Manager 
does  this  same  work  the  first  time  it  starts  up,  but  caches  all  the  information  it 
compiles  in  a  file  called  FONT.USTS  in  the  FONTS  folder. 

The  next  time  the  Font  Manager  starts  up,  it  checks  all  the  creation  and  modification 
dates  and  times  in  font  files  against  the  information  in  FONT.USTS.  It  compiles  new 
FONT.LISTS  information  only  if  it  finds  new  font  files  or  odier  evidence  of  change. 
Otherwise,  it  simply  starts  up  with  the  information  stored  in  the  FONT.LISTS  file.  In 
most  cases,  because  it  doesn't  have  to  open  every  font  file,  the  Font  Manager  can  start 
up  much  more  quickly. 

■  A  bug  has  been  fixed  in  the  chooseFont  call.  Previously,  ChooseFont  would  hang 
the  system  if  any  update  events  were  pending  when  the  call  was  made.  Now, 
ChooseFont  will  not  hang  the  system  under  these  circumstances;  the  system  leaves 
update  events  in  the  Event  Queue  for  processing  by  the  application. 

■  In  addition,  the  ChooseFont  dialog  now  uses  Newwindow2,  with  a  control  template 
that  can  be  kept  in  a  resource  file.  As  a  result,  this  dialog  can  be  internationalized  more 
easily. 

■  Scaled  fonts  may  now  contain  more  than  65,535  bytes  of  data.  See 

Chapter  43,  "QuickDraw  11  Update,"  later  in  this  book  for  the  layout  of  the  new  font 
record. 

■  A  bug  that  corrupted  the  font  family  list  has  been  fixed.  This  bug  had  varied 
symptoms,  including  incorrect  font  name  displays  in  the  Choose  Font  dialog  and  in  the 
Font  menu,  and  Font  Manager  crashes,  among  others. 
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New  call 

The  new  call  instaiiwithstats  is  provided  to  simpliiy  the  process  of  installing  fonts.  It  allows  an 
application  to  preserve  certain  information  that  is  normally  lost  during  font  installation. 


Instaiiwithstats  $1C1B 


Installs  a  font  and  returns  information  about  that  font.  When  an  application  requests  the 
installation  of  a  font,  the  Font  Manager  attempts  to  install  the  requested  font,  but  it  may 
not  be  available.  In  such  cases,  the  Font  Manager  will  install  the  closest  match  it  can  find 
to  the  requested  font. 

Instaiiwithstats  installs  a  font  just  as  if  the  application  had  called  instaiiFont, 
but  it  returns  a  FontstatRec  in  the  buffer  pointed  to  by  resultPtr.  This  record  contains 
the  ID  of  the  installed  font,  which  may  be  different  from  the  font  requested.  It  also 
contains  the  purge  status  that  the  font  had  before  it  was  installed,  Since  purge  status  can 
be  changed  by  installation,  this  information  can  make  it  easier  to  restore  a  font's  purge 
status.  If  you  need  to  know  an  installed  fonfs  purge  status,  use  FindFontstats. 

Parameters 

Stack  before  call 

Previous  contents 

desiredID     -  Long— Font  ID  of  desired  font 
scaleWord  Word— Desired  font  size 
resultPtr     -  Long— Pointer  to  buffer  to  receive  RontstatRec 
<— SP 

Stack  after  call 


PretHous  contents 


<— SP 


Errors 


None 
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C  extern  pascal  void  InstallWithStats (desiredID, 

scaleWord,   resultPtr) ; 

Long  desiredID; 
Word  scaleWord; 
Pointer  resultPtr; 

resultPtr  On  return  from  instaiiwithstats,  the  buffer  pointed  to  by 

resultPtr mH  contain  a  FontstatRec  formatted  as  follows 


$00 

resultID 

$04 

resultstats 

LcHig— Font  ID  record 

Word— FontstatBit  s  defining  font  status 
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Chapter  33  Integer  Math  Tool  Set  Update 


This  chapter  documents  changes  to  the  Integer  Math  Tool  Set.  The 
complete  reference  to  Integer  Math  is  in  Volume  1,  Chapter  9  of  the 
Apple  IIGS  Toolbox  Reference. 
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Clarifications 

■  The  Long2Dec  Integer  Math  tool  call  now  correctly  handles  input  long  values  that  have 
the  low-order  three  bytes  set  to  zero.  Previously,  if  the  input  long  had  its  low-order 
three  bytes  set  to  zero,  Long2Dec  would  always  return  a  zero  value,  even  if  the  high- 
order  byte  was  non-zero. 
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Chapter  34  LineEdit  Tool  Set  Update 


This  chapter  documents  new  features  of  the  LineEdit  Tool  Set.  The 
complete  reference  to  LineEdit  is  in  Volume  1,  Chapter  10  of  the 
Apple  IIGS  Toolbox  Reference. 
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New  features  in  LineEdit 

■  LineEdit  now  supports  password  fields.  Password  fields  do  not  echo  user  input  as 
typed.  Instead,  each  input  character  is  echoed  with  a  special  character.  Your 
application  can  set  the  echo  character;  the  default  is  asterisk  (*). 

The  LineEdit  edit  record  has  a  new  field,  lepwchar,  that  supports  the  password 
feature.  This  field  defines  the  screen  echo  character  for  password  fields.  It  is  located 
at  the  end  of  the  edit  record.  The  LineEdit  record  is  now  formatted  as  shown  in  Figure 
34-1. 

To  indicate  that  a  LineEdit  field  is  a  password  field,  set  the  high-order  bit  of  die 
maxSize  field  in  the  LineEdit  control  template  to  1  (see  "LineEdit  control  template"  in 
Chapter  28,  "Control  Manager  Update,"  eariier  in  this  book  for  more  information). 

■  Figure  34-1  shows  the  layout  of  the  new  LineEdit  record. 
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m   Figure  34-1     LineEdit  Edit  record  (new  layout) 


$00 

leLineHandle 

Long— Handle  to  text 

m 

leLength 

Word— Integer;  current  text  length 

$06 

leMaxLength 

Word— Integer;  maximum  text  length 

$08 

leDestRect 

Rectangle— Destination  rectangle 

$10 

leViewRect 

Rectangle— View  rectangle 

$18 

lePort 

Long — Pointer  to  GrafP ort 

$1C 

leLlneHite 

Word— Integer;  used  for  highlighting 

$1E 

leBaseHlte 

Word— Integer;  used  for  drawing  text 

$20 

leSelStart 

Word— Integer;  used  for  start  of  selection  range 

$22 

leSelEnd 

Word— Integer;  used  for  end  of  selection  range 

$24 

leActFlg 

Word— Reserved  for  internal  use 

$26 

leCarAct 

Word— Reserved  for  internal  use 

$28 

leCarOn 

Word— Reserved  for  internal  use 

$2A 

leCarTlme 

Long— Reserved  for  internal  use 

$2E 

leHlllteHook 

Long— Pointer  to  highlight  routine 

$32 

leCaretHook 

Long— Pointer  to  caret  routine 

$36 

leJust 

Word— Juaification  control  word 

$38 

lePWChar 

Word— Password  field  saeen  echo  character 
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leMaxLength     Indicates  the  maximum  text  length  allowed  in  the  LineEdit  field.  Valid 
values  range  from  1  to  255.  The  high-order  bit  governs  whether  the 
field  is  a  password  field.  If  the  bit  is  set  to  1,  then  the  field  is  a 
password  field,  and  user  input  is  echoed  with  character  values 
specified  by  the  contents  of  the  lepwchar  field. 

lepwchar         Defines  the  character  to  be  echoed  in  password  fields.  This  field 

contains  the  ASCII  code  for  the  echo  character  in  its  low-order  byte. 
Default  system  value  is  asterisk  (*). 
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New  call 

This  new  LineEdit  tool  call  returns  the  address  of  the  current  LineEdit  control  definition 
procedure. 


GetLEDefProc  $24l4 

Returns  the  address  of  the  current  LineEdit  control  definition  procedure.  The  system 
issues  this  call  when  the  Control  Manager  starts  up  in  order  to  obtain  the  address  of  the 
LineEdit  control  definition  procedure.  This  call  is  not  intended  for  application  use. 

Parameters 


Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result 
<— SP 


Previous  contents 


-    defProcPtr  - 


Long— Pointer  to  LineEdit  control  definition  procedure 
<— SP 


Errors 
C 


None 


extern  pascal  Pointer  GetLEDef Proc ( ) ; 
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Chapter  35  List  Manager  Update 


This  chapter  documents  new  features  of  the  List  Manager.  The  complete 
reference  to  the  List  Manager  is  in  Volume  1,  Chapter  11  of  the 
Apple  IIGS  Toolbox  Reference. 
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Clarifications 

■  The  Apple  DCS  Toolbox  Reference  states  that  a  disabled  item  of  a  list  cannot  be 
selected.  In  fact,  a  disabled  item  can  be  selected,  but  it  cannot  be  highlighted.  The 
List  Manager  provides  the  ability  to  select  disabled  (dimmed)  items  so  that  it  is 
possible,  for  instance,  for  a  user  to  select  a  disabled  menu  choice  as  part  of  a  help 
dialog.  To  make  an  item  unselectable,  set  it  inactive  (see  "List  Manager  definitions" 
later  in  this  chapter). 

■  Any  List  Manager  tool  call  that  draws  will  change  fields  in  the  GrafPort  If  you  are  using 
List  Manager  tool  calls  you  must  set  up  the  GrafPort  correctly  and  save  any  valuable 
GrafPort  data  before  issuing  the  call. 

■  Member  text  is  now  drawn  in  16  colors  in  both  320  and  640  mode. 

■  Previous  versions  of  List  Manager  documentation  do  not  clearly  define  the  relationship 
between  the  listview,  listMemHeight,  and  listRect  fields  in  the  list  record. 
To  clarify  this  point,  note  that  the  following  formula  must  be  tme  for  values  in  any  list 
record: 

(listview  'listMemHeight)  +  2  -  listRect.v2  -  listRect.vl 

If  you  set  listview  to  0,  the  List  Manager  will  automatically  adjust  the 
iistRect.v2  field  and  set  the  listview  field  so  that  this  formula -holds.  Note  that 
if  you  pass  a  0  value  for  listview  the  bottom  boundary  of  listRect  may  change 
slightly. 


List  Manager  definitions 

The  following  terms  define  the  valid  states  for  a  list  item. 

inactive  Bit  5  of  the  list  item's  memFiag  field  is  set  to  1.  Inactive  items  appear 

dimmed  and  annot  be  highlighted  or  selected. 

disabled  Bit  6  of  the  list  item's  memFiag  field  is  set  to  1.  Disabled  items  appear 

dimmed  and  cannot  be  highlighted. 

enabled  Bit  6  of  the  list  item's  memFiag  field  is  set  to  0.  Enabled  items  appear 

normal  and  can  be  highlighted. 

selected  Bit  7  of  the  list  item's  memFiag  field  is  set  to  1.  This  bit  is  set  when  a 

user  clicks  on  the  list  item,  or  the  item  is  within  a  range  of  selected  items. 
A  selected  item  appears  highlighted  only  if  it  is  also  enabled. 
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highlighted  A  member  of  a  list  appears  highlighted  only  when  it  is  both  selected  and 
enabled.  This  means  that  bit  7  of  the  memFiag  field  is  set  to  1  and  bit  6 
is  set  to  0.  A  highlighted  member  is  drawn  in  the  highlight  colors. 
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New  features  in  the  List  Manager 

■  The  latest  revision  of  the  List  Manager  includes  new  versions  of  the  tool  calls  that 
provide  more  flexible  interfaces  for  application  programmers  in  two  ways.  First,  these 
new  List  Manager  routines  allow  your  application  to  pass  an  item  number,  rather  than  a 
list  record  pointer,  to  identify  an  item  to  process.  This  frees  you  from  tracking  pointer 
values,  and  allows  you  to  focus  on  the  more  useful  item  number.  Second,  your 
application  need  no  longer  maintain  the  list  record.  All  new  tool  calls  allow  you  to 
identify  the  list  by  a  handle  to  the  list  control  record.  List  Manager  returns  this  handle 
atCreateList  or,  preferably,  NewControl2  time. 

■  The  1  i  s  t  Type  field  now  supports  a  flag  that  governs  where  the  scroll  bar  is  to  be 
created.  Bit  2  of  list  Type  determines  whether  the  scroll  bar  is  created  inside  or 
outside  of  listRect.  If  the  bit  is  set  to  1,  the  List  Manager  adjusts  the  right  side  of 
listRect  to  accommodate  the  scroll  bar,  creates  the  scroll  bar  inside  of  the  adjusted 
listRect,  and  then  sets  the  flag  to  0.  If  the  bit  is  set  to  0,  the  scroll  bar  resides 
outside  listRect.  This  works  the  same  way  with  old-style  control  records. 

A  Important     When  using  resources  with  the  List  Manager,  be  careful  to  define  the 
memory  referenced  by  listRef  (see  °NewList2"  later  in  this  chapter) 
as  unpurgeable  if  you  plan  to  use  the  sortList  caM.  Otherwise,  in 
response  to  a  memory  allocation  request,  the  sorted  list  may  be 
purged  from  memory.  Then,  when  your  application  next  issues  a  List 
Manager  call,  the  system  will  reload  the  unsorted  list,  a 
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New  List  Manager  calls 

The  following  new  List  Manager  calls  support  a  new,  more  flexible  programming  interface. 
In  general,  these  calls  provide  the  same  functionality  as  the  old  versions. 


DrawMember2  $111C 

Draws  one  or  all  members  of  a  specified  list.  If  your  application  goes  directly  to  the 
member  record  to  change  the  state  of  a  member,  the  application  should  then  call 
DrawMember  orDrawMember2.  Unlike  DrawMember,  this  call  accepts  an  item  number 
specification  for  the  member  to  draw.  Passing  an  item  number  of  0  causes  the  List 
Manager  to  redraw  the  entire  list. 

Parameters 

Stack  before  call 


Previous  contents 


itemNum 


ctlHandle  - 


Word — Item  number  to  redraw 
Long— Handle  of  the  list  control 
<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 
C 


None 


extern  pascal  void  DrawMember2 (itemNum,   ctlHandle) ; 

Word  itemNum; 
Handle  ctlHandle; 
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NewList2  $161C 

Resets  the  list  control  according  to  a  specified  list  record.  Your  application  passes  the 
parameters  controlling  the  creation  of  the  list  on  the  stack,  rather  than  in  a  list  record  (as 

with  NewList). 

Parameters 

Stack  before  call 


Previous  contents 


drawPtr 


listStart 


listRef 


listRepesc 


HstSize 


ctlHandle 


Stack  after  call 


Long— Pointer  to  member  draw  routine;  NIL  for  default  routine 

Word— Item  number  of  first  displayed  list  member 

Long— Reference  to  list 

Word— Descriptor  for  listRef 
Word— Number  of  items  in  the  list 

Long— Handle  of  the  list  control  returned  by  NewControi2 

<— SP 


Previous  contents 


Errors 
C 


drawPtr 


None 


<— SP 


extern  pascal  void  NewList2 (drawPtr,  listStart, 
listRef,  listRefDesc,  listSize, 
CtlHandle) ; 

Pointer  drawPtr; 

Word  listStart,   listRefDesc,  listSize; 

Long  listRef; 
Handle  ctlHandle; 

Pointer  to  custom  list  member  drawing  routine.  NIL  value  causes  the 
List  Manager  to  use  its  standard  routine. 
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listStart  Item  number  of  first  list  item  to  display.  A  value  of  $FFFF  tells  the  List 

Manager  to  use  the  value  currently  stored  in  the  list  control  record. 
Never  set  this  parameter  to  0. 

listRef  Reference  (pointer,  handle,  or  resource  ID)  to  the  list.  The  value  of 

lisiRefDesc  governs  how  the  Dst  Manager  interprets  this  field.  A  value 
of  $FFFFFFFF  tells  the  List  Manager  to  use  the  value  currently  stored  in 
the  list  control  record. 

listReJDesc  Defines  the  type  of  reference  stored  in  listRef. 

0  listRef  reference  is  a  pointer 

1  listRef  reference  is  a  handle 

2  listRef  rekrence  is  a  resource  ID 
$FFFF  no  change 


♦  Note:  If  you  set  either  listRef  or  listRepesc  to  -1,  then  you  must  set  the  other  field  to 
the  same  value. 


listSize  Number  of  entries  in  the  list.  A  value  of  $FFFF  tells  the  List  Manager  to 

use  the  value  currently  stored  in  the  list  control  record. 
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NextMember2  $121C 

Searches  a  specified  list  record,  starting  with  a  specfied  item,  and  returns  the  item  number 
corresponding  to  the  next  selected  item.  This  call  accepts  an  item  number  and  control 
handle  as  input.  If  you  pass  an  item  number  of  0,  the  Dst  Manager  starts  its  search  from 
the  beginning  of  the  list. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Word— Space  for  result 

Word— Item  number  of  starting  point  for  search 
Long— Handle  of  the  list  control 


itemNum 


ctlHandle  - 


<— SP 


Stack  after  call 


Previous  contents 


itemNum 


Word— Item  number  of  selected  member;  0  if  no  more 


<— SP 


Errors 


None 


C 


extern  pascal  Word  NextMeinber2  (itemNum,  ctlHandle)  ; 


Word 


Handle 


itemNum; 
CtlHandle; 
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ResetMember2  $131C 

Searches  a  specified  list  control,  starting  with  the  first  list  member,  and  returns  the  item 
number  of  the  first  selected  member  in  the  list.  If  the  user  has  not  selected  a  member,  then 
the  returned  item  number  is  0.  This  call  accepts  a  control  handle  as  input. 

Parameters 

Stack  before  call 

Previous  contents 


ctlHandle 


Space 


Word— Space  for  result 
Long— Handle  of  the  list  control 


<— SP 


Stack  after  call 


Previous  contents 


itemNum 


Word— Item  number  of  selected  member;  0  if  no  more 


<— SP 


Errors 


None 


C 


extern  pascal  Word  ResetMember2 (ctlHandle) ; 


Handle 


CtlHandle; 
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SelectMember2  $l4lC 

Selects  a  specified  member,  deselects  any  other  selected  members  of  the  list,  and  scrolls 
the  list  display  so  that  the  specified  member  is  at  the  top  of  the  display.  This  call  accepts 
a  control  handle  and  an  item  number  as  input. 

Parameters 

Stack  before  call 


Previous  contents 


itemNum 


ctlHandle  - 


Stack  after  call 


Word— Item  number  of  member  to  select 
Long— Handle  of  the  list  control 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  SelectMember2 (itemNum, 
CtlHandle)  ; 

Word  itemNum; 
Handle  ctlHandle; 
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SortList2  $151C 

Alphabetizes  a  specified  list  by  rearranging  the  array  of  member  records.  This  call  accepts 
a  control  handle  and  a  pointer  to  a  custom  comparison  routine  as  input. 

Parametefs 

Stack  before  call 


Previous  contents 


-    comparePtr  - 


Long— Pointer  to  comparison  routine;  NIL  for  standard  compare 


ctlHandle  - 


Long— Handle  of  the  list  control 


<— SP 


Stack  after  call 


Prmous  contents 


<— SP 


Errors 


None 


C 


extern  pascal  void  SortList2 (conparePtr,  ctlHandle); 


Pointer 


conparePtr; 
CtlHandle; 


Handle 
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Chapter  36  Memory  Manager  Update 


This  chapter  documents  new  features  of  the  Memory  Manager.  The 
complete  reference  to  the  Memory  Manager  is  in  Volume  1,  Chapter  12  of 
the  Apple  IIGS  Toolbox  Reference. 
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Error  correction 

On  page  12-10  of  the  Toolbox  Reference,  Figure  12-7  shows  the  low-order  bit  of  the  User  E) 
is  resented.  This  is  not  correa.  The  figure  should  show  that  the  mainiD  field  comprises 
bits  0-7,  and  that  the  mainiD  value  of  $00  is  reserved. 


Clarification 


The  Toolbox  Reference  documentation  of  the  SetHandieSize  call  ($1902)  states  "If  you 
need  more  room  to  lengthen  a  block,  you  may  compact  memory  or  purge  blocks."  This  is 
misleading.  In  fact,  to  satisfy  a  request  the  Memory  Manager  will  compact  memory  or 
purge  blocks  in  order  to  free  sufficient  contiguous  memory.  Therefore,  the  sentence 
should  read  "If  your  request  requires  more  memory  than  is  available,  the  Memory  Manager 
may  compact  memory  or  purge  blocks,  as  needed." 


New  features  in  the  Memory  Manager 

The  Memory  Manager  allocates  handles  much  faster  than  before.  The  Memory  Manager 
remembers  the  last  handle  allocated,  and  starts  its  search  for  new  memory  from  that 
location,  resulting  in  improved  allocation  time. 


Out-of-memory  queue 

The  out-of-memory  queue  allows  application  code  to  gracefully  recover  from  low- 
memory  conditions  in  the  system.  The  out-of-memory  queue  consists  of  a  series  of  out- 
of-memory  routines,  which  are  created  and  installed  by  application  programs.  When  the 
Memory  Manager  cannot  create  a  handle  from  memory  currently  available,  it  calls  each  of 
the  out-of-memory  routines.  These  routines  can  then  either  free  up  memory  that  is  not 
crucial  to  the  function  of  an  application,  or  notify  the  application  that  it  is  time  to  tell 
the  user  to.save  and  exit. 
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When  the  Memory  Manager  encounters  a  low-memory  condition,  it  performs  the  following 
steps: 

1 .  Invokes  each  out-of-memory  routine  until  a  routine  reports  that  it  has  freed  enough 
memory  to  satisfy  the  request.  If  a  routine  does  free  enough  memory,  the  Memory 
Manager  then  allocates  the  handle  and  returns  control  to  the  calling  application. 

2.  Compacts  memory  and  retries  the  allocation.  If  the  allocation  is  successful,  the 
Menwry  Manager  returns  control  to  the  calling  application. 

3.  Purges  Level  3  handles.  If  this  frees  enough  memory,  the  Memory  Manager  compacts 
memory,  allocates  the  handle,  and  returns  to  the  ailing  application. 

4.  Pulses  Level  2  handles.  If  this  frees  enough  memory,  the  Memory  Manager  compacts 
memory,  allocates  the  handle,  and  returns  to  the  calling  application. 

5.  PuigesLevel  1  handles.  If  this  frees  enough  memory,  the  Memory  Manager  compacts 
memory,  allocates  the  handle,  and  returns  to  the  calling  application. 

6.  Again  invokes  each  out-of-memory  routine.  If  a  routine  frees  enough  memory,  the 
Memory  Manager  allocates  the  handle  and  returns  to  the  application.  Otherwise,  the 
Memory  Manager  reports  an  out-of-memory  condition  to  the  application. 

Note  that  the  Memory  Manager  may  invoke  an  out-of:memory  routine  twice  during  the 
same  low-memory  condition.  In  the  invokation  parameter  block  for  an  out-of-memory 
routine,  the  Memory  Manager  passes  a  flag  indicating  whether  this  is  the  first  or  second 
time  through  the  out-of-memory  queue.  By  examining  this  flag,  routines  can  react 
differently  based  upon  the  urgency  of  the  low-memory  condition. 

Any  application,  desk  accessory,  or  init  that  installs  an  out-of-memory  routine  must  also 
remove  that  routine  from  the  out-of-memory  queue.  Add  routines  to  the  queue  with  the 
AddToooMQueue  tool  call;  remove  them  with  the  RemoveFromooMQueue  tool  call. 

Out-of-memory  routines  may  use  any  Memory  Manager  tool  call.  However,  routines  that 
must  issue  calls  that  allocate  memory  (such  as  NewHandie)  should  reserve  the  needed 
memory  at  initialization,  so  that  the  space  will  be  available  during  a  low-memory 
condition.  For  example,  if  you  want  your  out-of-memory  routine  to  save  some  user  data 
to  disk  before  purging  a  memory  block,  your  application  should  reserve  enough  memory 
for  the  file  open  before  installing  the  routine.  When  the  routine  gains  control,  it  can  then 
free  the  reserved  memory,  issue  the  file  system  calls,  and  purge  the  unneeded  application 
memory  without  aeating  a  recursive  low-memory  condition.  See  the  code  example  for 
sample  application  and  out-of-memory  routine  code. 
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An  out-of-memory  routine  must  be  preceded  by  a  header  formatted  as  follows: 


$00 

Reserved 

Long— Used  by  system  as  link  to  next  queue  item 

m 

version 

Wad— Must  be  set  to  0 

$06 

signature 

Word— Header  signature,  to  ensure  integrity— set  to  $A55A 

version  Allows  System  to  discriminate  between  current  and  future  types  of 

out-of-memory  routines.  Must  be  set  to  0. 

signature        Used  by  the  system  to  ensure  that  the  header  is  well-formed.  The  value 
of  this  field  must  be  $A55A. 

The  out-of-memory  routine  code  must  immediately  follow  the  signature  word.  If  the 
Memory  Manager  finds  an  invalid  header  for  any  out-of-memory  routine,  it  terminates 
with  a  system  death  error  code  of  $0209. 

When  the  out-of-memoiy  routine  gets  control,  the  Memory  Manager  will  have  formatted 
the  input  stack  as  follows: 


Previous  contents 


Space 


-    bytesNeeded  - 


stage 


RTLAddr  - 


stage 


Long— Space  for  result 

Long— Number  of  bytes  the  Memory  Manager  needs 
Word— Flagword  indicating  stage  of  low-memory  condition 
3  Bytes— Retum  address 
<— SP 


Indicates  the  stage  of  the  low-memory  condition.  This  flag  allows  the 
routme  to  determine  whether  this  is  the  first  or  second  invokation  for 
this  condition.  If  the  field  is  set  to  0,  then  this  is  the  first  invokation, 
and  the  Memory  Manager  has  not  done  anything  else.  If  the  field  is  set 
to  1,  then  this  is  the  second  invokation  for  this  low-memory 
condition,  and  the  Memory  Manager  will  report  an  out-of-memory 
condition  to  the  calling  application  if  it  cannot  find  enough  memory 
to  satisfy  the  request. 
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The  out-of-memory  routine  must  strip  off  the  input  parameters  and  return  the  number  of 
bytes  freed  in  the  space  provided.  On  exit,  therefore,  the  routine  should  format  the  stack 
as  follows: 

Previous  contents 


Out-of-memory  Routine  example 

The  following  code  example  has  two  parts:  the  first  shows  how  your  application  can  install 
a  routine  in  the  out-of-memory  queue;  the  second  is  a  sample  out-of-memory  routine. 

;  first  allocate  a  handle  with  enough  memory  for  our  low  memory  exit 
;  this  exarr$>le  will  use  a  16k  handle 


-  amountFreed  - 


Long— Number  of  bytes  of  memory  freed  by  routine 


RTLAddr 


3  Bytes— Return  address 


<— SP 


pha 
pha 

PushLong  #$4000 
PushWord  MylD 
PushWord  #0 
PushLong  #0 
_NewHandle 
PullLong  ResvHand 


size  of  handle 

my  applications  ID 

no  bits  set,  unlocked  and  moveable 

address   (Not  used) 


and  pull  off  the  reserve  handle 


room  for  result  ' 


PushLong  #MyOOMRtn 
AddToOOMQueue 


address  of  the  COM  header 


St 2  OOMFlag 


zero  our  low  memory  indicator 


Note  that  this  application  maintains  the  ooMFiag  field  in  its  global  storage  area. 
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The  following  is  the  actual  out-of-memory  queue  entry  itself.  It  has  been  written  for  the 
MPW™  Apple  IIGS  assembler. 


This  is  the  OOMQueue  header  for  our  routine 


MyOOMRtn  Record 
dc.L  0 
dc.W  0 
dc.W  $A55A 
EndR 


;  used  by  cjueue  manager 

;  OOMEntry  version 

;  queue  entry  signature 


Now  for  my  out-of-memory  routine 


MyOOM 


proc 


first  set  up  the  equates  for  the  stack  frame  passed  to  us  by  the 
memory  mgr 


RTLAdr  equ  1  ;   return  address  we  will  go  back  to 

Stage  equ  RTLAdr+3  ;  indicates  when  called 

BytesNeeded  equ  Stage+2  ;  number  of  bytes  the  mem  mgr  needs 

Result  equ  BytesNeeded+4  ;  return  niunber  of  bytes  freed 


before  we  start  we  should  zero  out  the  result 


Ida  #0 

sta  Result, s 
sta  Result+2,s 


;  zero  the  result  on  the  stack 


Since  this  routine  can  be  called  before  and  after  purging  data 

we  want  to  wait  till  the  memory  manager  has  purged  everything  it  can 

before  we  panic  so  the  first  thing  we  do  is  test  the  Stage 


Ida  Stage, s 
beq  OOMEnd 


;  get  the  passed  stage 

;  if  0  then  don't  free  anything 


Now  that  we  know  that  the  memory  manager  has  tried  everything  else, 
we  test  to  see  if  we  have  done  this  before  by  testing 
the  OOMFlag 


Ida  >OOMFlag 
bne  OOMEnd 


;  must  use  long  address  DB=unknown 

;  if  non-zero  then  memory  already  free 
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since  we  know  that  we  have  not  freed  the  reserve  memory  yet 
we  will  do  so  now  and  set  the  flag. 

PushLong  >ResvHand  ;  handle  to  our  reserve  space 

_DisposeHandle         ;  and  dispose  of  it 


Ida  #$FFFF 
sta  >OOMFlag 


;  now  set  our  flag  to  true 

;  so  that  the  event  loop  knows  low  mem 


Ida  #$4000 
sta  Result, s 


and  signal  the  memory  manager  how 
much  mem  we  freed 


;  Now  return  to  the  memory  manager  first  adjusting  the  stack  to  remove 
the 

;  passed  params 


OOMEnd 


LongA  Off 
SEP  #$20 


;  turn  on  8  bit  accumulator 


pla 
ply 


;  load  the  return  address  for  safe 
;  keeping  for  a  sec 


plx 
plx 
plx 


;  now  pull  off  6  bytes  of  parameters 


phy 
pha 

LongA  On 
REP  #$20 


;  put  the  return  addr  back 


;  turn  on  16  bit  accumulator 


RTL 


;  and  return 
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New  Memory  Manager  calls 

ReaiFreeMem  is  a  new  Memory  Manager  call  designed  to  provide  accurate  information 
about  available  memory.  Other  new  Memory  Manager  calls  support  the  out-of-memory 
queue. 


AddToOOMQueue  $0C02 

Adds  the  specified  out-of-memory  routine  to  the  head  of  the  out-of-memory  queue.  The 
input  routine  pointer  should  contain  the  address  of  the  routine  header  block. 

Parameters 

Stack  before  call 


Previous  contents 


headerPtr 


Stack  after  call 


Long— Pointer  to  out-of-memory  routine 
<-SP 


Previous  contents 


Errors 


$0381 


<— SP 
invalidTag 


Correct  signature  value  not  found 
in  header 


extern  pascal  void  AddToOOMQueue (headerPtr) ; 
Pointer  headerPtr; 
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RealFreeMem  $2F02 

Returns  the  number  of  bytes  in  memory  that  are  free,  plus  the  number  that  could  be  made 
free  by  purging.  FreeMem  only  returns  the  number  of  bytes  that  are  actually  free,  ignoring 
memory  that  is  occupied  by  unlocked  purgeable  blocks.  Since  unlocked  blocks  of 
allocated  memory  can  be  freed  by  purging,  FreeMem  does  not  provide  an  accurate 
picture  of  the  memory  that  is  actually  available.  RealFreeMem  provides  a  more  accurate 
value. 

Parameters 

Stack  before  call 

Prmous  contents 


Space 


Long— Space  for  result 


<— SP 


Stack  after  call 


Prmous  contents 


freeBytes 


Long— Number  of  available  bytes  in  memory 


<— SP 


Errors 


None 


C 


extern  pascal  Long  RealFreeMem () ; 
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RemoveFromOOMQueue  $0D02 

Removes  the  specified  out-of-memory  routine  from  the  queue.  The  input  routine  pointer 
should  contain  the  address  of  the  routine  header  block. 

Parameters 

Stack  before  call 


Previous  contents 


headerPtr 


Stack  after  call 

Previous  contents 


Errors 


$0381 
$0380 


Long— Pointer  to  out-of-memory  routine 
<— SP 


<— SP 
invalidTag 

notlnList 


Correct  signature  value  not  found 
in  header 

Specified  routine  not  found  in 
queue 


extern  pascal  void  RemoveFromOOMQueue (headerPtr) ; 
Pointer  headerPtr; 
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Chapter  37  Menu  Manager  Update 


This  chapter  documents  new  features  of  the  Menu  Manager.  The 
complete  reference  to  the  Menu  Manager  is  in  Volume  1,  Chapter  13  of 
the  Apple  IIGS  Toolbox  Reference. 
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Error  corrections 

■  In  the  description  of  the  setSysBar  tool  call  (pages  13-86  and  13-3),  the  Toolbox 
Reference  states  that,  after  an  application  issues  this  call,  the  new  system  menu  bar 
becomes  the  current  menu  bar.  This  is  incorrect.  Your  application  must  issue  the 
setMenuBar  tool  call  to  make  the  new  menu  bar  the  current  menu  bar. 

■  In  the  definition  of  the  menu  bar  record  (pages  13-17-18),  the  Toolbox  Reference  shows 
that  bits  0-5  of  the  ctiFiag  field  are  used  to  indicate  the  starting  position  for  the 
first  title  in  the  menu  bar.  This  is  incorrect.  The  ctiHiiite  field  defines  the  starting 
position  for  the  first  title.  Note  further  that  the  entire  ctiHiiite  field  is  used  in  this 
manner.  The  documented  purpose  of  the  ctiHiiite  field  (number  of  highlighted 
titles)  is  not  supported  by  the  Menu  Bar  record. 


Clarifications 

■  The  setBarCoiors  tool  call  changes  the  color  table  for  all  menu  bars  in  a  window.  If 
you  want  to  use  separate  color  tables  for  different  menu  bars,  your  application  must 
build  a  menu  bar  color  table  and  modify  the  cticoior  field  of  the  appropriate 
control  record  to  point  to  this  custom  color  table.  See  "SetBarColor"  in 

Chapter  13,  "Menu  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for  the  format  and 
contents  of  a  menu  bar  color  table. 

■  The  description  of  the  insertMenu  tool  call  should  also  note  that  your  application 
must  call  FixMenuBar  before  calling  DrawMenuBar  in  order  to  display  the  modified 
menu  bar. 

■  The  description  of  the  initPaiette  tool  call  in  the  Toolbox  Reference  should  also 
note  that  the  call  changes  color  tables  1  through  6  to  correspond  to  the  colors  needed 
for  drawing  the  Apple  logo  in  its  standard  colors. 

■  The  CaicMenuSize  call  uses  the  newWidth  and  newHeight  parameters  to  compute  a 
menu's  size.  These  parameters  may  contain  the  width  and  height  of  the  menu,  or  may 
contain  the  values  $0(XX)  or  $FFFF.  A  value  of  $0000  tells  c<    MenuSize  to  calculate 
the  parameter  automatically.  A  value  of  $FFFF  tells  it  to  calculate  the  parameter  only  if 
the  current  setting  is  0. 
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The  effect  of  all  three  uses: 

□  Pass  the  new  value.  The  value  passed  will  become  the  menu's  si2e.  Use  this 
method  when  a  specific  menu  size  is  needed. 

o  Pass  $0000.  The  size  value  will  be  automatically  computed.  This  option  is  useftjl  if 
menu  items  are  added  or  deleted,  rendering  the  menu's  size  incorrect.  The  menu's 
height  and  width  can  be  automatically  adjusted  by  calling  caicMenuSize  with 
newWidth  and  newHeight  equal  to  $0000. 

□  Pass  $FFFF.  The  width  and  height  of  a  menu  is  0  when  it  is  created.  FixMenuBar 
calls  CaicMenuSize  with  newWidthznd  newHeight eqm\  to  $FFFF  to  calculate 
the  sizes  of  those  menus  with  heights  and  widths  of  0. 
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New  features  in  the  Menu  Manager 

This  section  lists  several  new  features  of  the  Menu  Manager,  and  some  information  that 
was  not  previously  dear. 

■  Menus  in  windows  can  now  display  the  Apple  character  (ASCII  $14),  though  it  will  not 
be  multicolored. 

■  Menus  now  use  their  outline  color  for  lines  that  separate  menu  items. 

■  The  NewMenuBar  call  automatically  sets  bit  31  of  the  ctiowner  field  in  the  menu  bar 
record  to  1,  if  the  designated  menu  bar  is  a  window  menu  bar  (the  value  passed  for  the 
window  is  not  0). 

■  The  default  position  for  the  first  menu  title  in  a  menu  bar  is  10  pixels  indented  from  the 
left  edge  of  the  screen,  m  640  mode;  in  320  mode  the  item  is  indented  5  pixels. 

■  The  Menu  Manager's  justification  procedures  adjust  for  menu  bars  in  windows.  Menus 
will  be  nvoved  to  the  left  if  they  would  otherwise  appear  to  the  right  of  the  menu  bar's 
right  end. 

■  The  default  menu  bar  has  the  following  coordinates:  top  -  0;  left  -  0;  height "  13; 
width  -  the  width  of  the  screen. 

■  MenuShutDown  does  not  retum  an  error  if  the  Menu  Manager  has  already  been  shut 
down. 

■  Your  application  can  now  create  empty  menus.  To  create  an  empty  menu,  set  the  first 
byte  in  the  first  menu  line  item  to  either  null  ($00)  or  return  ($0D),  signifying  the  end  of 
the  menu  definition.  For  example: 


dc.b  '$$  Ert^ty  Menu  \N1',$00 
dc.b  $00 


menu  title  and  ID 

first  character  in  first 
item  to  null   (or  return) 
indicates  end  of  menu  def . 


Or,  using  a  menu  template: 

EmptyMenu 

dc.W  0 


;  version 
;  menu  id 
;  menu  flag 
;  menu  title 

;  indicates  end  of  item  list 


dc.W 


1 


Title  str 


dc.W 


dc.L 


dc.L 


0 

Title 
$00000000 
'Empty  Menu' 
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m  The  Menu  Manager  now  correctly  supports  outline  and  shadow  text  styles.  As  a  result, 
the  existing  7bo/^ax /?e/erewce  description  of  the  setMitemstyie  tool  call,  and  the 
menu  text  style  word  defined  in  that  description,  is  now  correct. 
In  addition,  the  Menu  Manager  now  supports  two  new  special  characters  for  menu 
definition; 

O  Outline  the  text 
S  Shadow  the  text 

Other  special  characters  are  listed  on  page  13-14  of  Volume  1  of  the  Toolbox  Reference. 
Note  that  this  feature  requires  the  QuickDraw  II  Auxiliary  Tool  Set. 

■  Menus  now  scroll  up  or  down  if  their  items  will  not  fit  on  the  screen.  When  a  menu  is 
scrollable  in  a  direction,  an  arrow  indicator  appears  at  the  appropriate  end  of  the 
menu,  signifying  that  there  are  more  items  available.  See  Figure  37-1. 

The  indicator  does  not  highlight,  but  the  menu  contents  scroll  when  the  user  drags  over 
it.  When  the  last  item  is  displayable,  the  indicator  disappears.  Indicators  may  appear 
at  both  the  top  and  bottom  of  a  menu,  if  appropriate. 

Menus  scroll  at  two  speeds,  depending  upon  where  the  user  drags  in  the  indicator.  If 
the  user  drags  within  the  first  five  pbcels  of  an  indicator,  scrolling  runs  at  its  slow  speed. 
Dragging  anywhere  beyond  this  point  results  in  fast  scrolling. 


■   Figure  37-1     Scrolling  menus  with  indicator  at  bottom 


2400 
4800 
9600 


2400 
4800 
9600 


♦  Note:  If  your  application  defines  menus  within  a  moveable  window,  dragging  that 
window  close  to  the  bottom  of  the  screen  may  force  some  of  the  menus  to  be 
scrollable.  If  there  is  not  room  for  three  visible  items  (up  and  down  indicators  and  one 
menu  item),  then  the  menu  will  drop  below  the  visible  screen  area. 
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■  The  menu  record  has  been  slightiy  modified.  The  f  irstitem  and  numof  items  byte 
fields  have  been  combined  into  a  single  word  field,  numof  items,  at  offset  $0C  into 
the  record.  This  field  specifies  the  number  of  items  in  the  menu. 

■  Bit  8  of  the  flag  field  in  the  menu  record  is  now  defined  as  the  aiwaysCaiimChoose 
flag.  When  this  flag  is  set  to  1,  the  Menu  Manager  calls  the  mChoose  routine  in  the 
defProc  for  a  custom  menu  even  when  the  mouse  is  not  within  the  menu  rectangle.  This 
feature  supports  tear-off  menus. 

■  Keyboard  equivalents  and  check  marks  now  appear  in  plain  text  regardless  of  the  style 
of  the  associated  menu  item. 

■  The  Menu  Manager  can  now  handle  large  fonts  in  menus. 


Menu  caching 

The  current  version  of  the  Menu  Manager  introduces  new  menu  caching  features.  Menu 
caching  is  designed  to  provide  faster  display  of  menus  under  certain  circumstances.  When 
a  menu  is  drawn  on  the  screen,  the  area  of  the  saeen  that  it  covers  is  copied  into  a  buffer. 
When  the  menu  goes  away,  the  contents  of  the  buffer  are  copied  back  to  the  screen. 

With  the  menu  caching  feature,  when  the  saved  screen  image  is  copied  back  to  the  screen, 
the  menu  that  goes  away  is  copied  into  the  buffer.  In  other  words,  the  Menu  Manager 
swaps  the  menu  image  with  the  screen  image.  Therefore,  the  next  time  that  menu  is  pulled 
down,  the  Menu  Manager  can  copy  it  from  the  buffer  instead  of  drawing  a  new  image. 

If  the  menu  image  changes— for  example,  an  item  is  disabled  or  the  items  on  the  menu 
change — then  the  cached  image  is  inaccurate,  and  the  Menu  Manager  must  redraw  the 
menu.  In  those  cases  where  a  menu  image  does  not  change,  the  menu  bar  can  respond  to 
the  user  more  quickly. 

Menu  caching  should  not  increase  memory  requirements,  because  menu  images  are 
purgeable  when  not  displayed  on  the  screen. 

This  menu  caching  scheme  should  work  properly  with  all  existing  standard  menus.  You  will 
have  to  alter  custom  menus,  however,  so  that  they  can  take  advantage  of  menu  caching. 
Custom  menus  will  still  function  normally,  as  long  as  they  do  not  change  the  menu  record 
direcdy,  but  they  will  not  be  able  to  take  advantage  of  the  menu  caching  scheme  to  speed 
up  display. 

Caching  does  not  work  with  menus  in  windows,  so  the  insertMenu  call  automatially 
disables  caching  for  such  menus. 
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Caching  with  custom  menus 

Bit  3  of  the  MenuFlag  field  in  a  menu  record  indicates  whether  a  menu's  definition 
procedure  knows  about  caching.  A  value  of  1  indicates  that  the  menu  in  question  is 
cacheable,  A  custom  menu  that  uses  caching  must  defmea  menu  record  that  sets  this  flag 
and  allocates  an  extra  field,  a  handle  to  the  cache  in  which  the  menu  image  will  be  stored, 
as  shown  in  the  following  figure. 


$00 

menuID 

Word-Menu's  ID  number 

$02 

menuWidth 

Word— Width  of  menu 

$04 

menuHelght 

Word— Height  of  menu 

$06 

menuProc 

Long— Pointer  to  menu  definition  procedure 

$0A 

menuFlag 

Byte— Flags  (bit  3  set  to  1  for  cached  menus) 

$0B 

menuRes 

Byte— Reserved 

$0C 

numOf Items 

Word— Number  of  menu  items 

$0E 

titleWidth 

Word— Width  of  title 

$10 

tltleName 

Long— Pointer  to  title  string  for  menu 

$14 

menuCache 

Long— Handle  to  cache  for  menu  image 
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Pop-up  menus 

Menu  Manager  now  supports  pop-up  menus.  Pop-up  menus  exist  in  a  window,  not  in  the 
menu  bar.  Figure  37-2  shows  a  window  with  pop-up  menus.  The  screen  representation  of  a 
pop-up  is  a  box  with  a  one-pixel-thick  drop  shadow.  When  the  user  dicks  the  mouse 
inside  the  pop-up  box,  the  menu  appears,  with  the  current  value  highlighted  under  the 
arrow,  as  shown  in  Figure  37-3.  If  the  menu  has  a  title,  the  tide  is  highlighted  whenever  the 
menu  is  visible. 

Pop-up  menus  work  in  the  same  way  as  other  menus:  the  user  can  move  around  within  the 
menu,  select  an  item  by  positioning  over  it,  or  not  select  any  item  by  dragging  outside  the 
menu.  Pop-up  menus  support  scrolling,  if  it  is  needed  to  view  all  the  menu  items.  Pop-up 
menus  are  useful  for  setting  values  or  choosing  from  lists  of  related  values. 

Pop-up  menus  support  most  of  the  standard  features  and  calls  available  with  standard 
menus; 

■  Pop-up  menu  items  support  keystroke  equivalents.  Pop-up  menus  will  display  the 
equivalent  (Apple  logo  with  character).  Note  that  if  a  pop-up  item's  keystroke 
equivalent  conflicts  with  a  standard  menu  item  equivalent,  the  pop-up  menu  may  not 
receive  the  keystroke.  TaskMaster  passes  the  keystroke  to  the  system  first,  unless  the 
tmControiKey  flag  in  the  wmTaskMask  field  of  the  task  record  is  set  to  0  (do  not 
pass  keys  to  controls  in  the  active  window). 

■  Pop-up  menu  items  can  be  dimmed  to  indicate  that  they  are  disabled  and  cannot  be 
chosen, 

■  Each  item  in  a  pop-up  menu  can  have  its  own  text  styles. 
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u   Figure  37-2     Window  with  pop-up  menus 


Pop-up  title 


Pop-up  box 


Modem  setup... 


Baud  rate: 


300 


Bits  per  character:     7  j 


Stop  bits: 


Parity: 


Euen 


Q  Cancel  ^  ^    OK  ^ 
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Figure  37-3     Dragging  through  a  pop-up  menu 


Inverted 
pop-up  title 


110 

Baud  rate: 

600  tV 
1200  tH 
2400 
4800 
9600 

Pop-up  item 

/ 


V  

110 

Baud  rate: 

500 

600 

1200 

2400 

4800  K 

9600 

Pop-up  menu  scrolling  options 

There  are  two  types  of  pop-up  menus,  which  are  distinguished  by  their  support  for 
scrolling;  type  1  pop-up  menus  and  type  2  pop-up  menus. 

The  Menu  Manager  determines  the  size  rectangle  into  which  to  draw  a  type  1  pop-up  menu 
based  upon  the  relative  position  of  the  current  item  within  the  menu  and  the  window 
constraints  of  the  pop-up  menu  (see  Figure  37-4).  The  Menu  Manager  draws  the  pop-up 
menu  with  the  current  item  highlighted  and  positioned  adjacent  to  the  menu  title.  The 
menu  extends  up  and  down  only  as  far  as  is  necessary  to  display  the  remaining  items  in 
each  direction,  and  indicators  as  appropriate,  within  the  boundary  rectangle  for  the 
window.  Therefore,  with  type  1  pop-up  menus,  it  is  possible  to  obtain  a  display  such  as 
that  shown  in  Figure  37-4,  where  the  user  can  display  only  a  single  item. 
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Figure  374     Type  1  pop-up  menu 


Baud  rate: 

9600 

Bits  per  character: 
Stop  bits: 

Parity: 


Euen 


C  cancel  }  ^    OK  ^ 


When  the  Menu  Manager  needs  to  make  a  type  2  pop-up  menu  scrollable,  it  creates  a  menu 
that  is  long  enough  to  receive  all  the  menu  items,  within  the  bounds  of  the  screen.  In  this 
manner,  the  user  never  sees  a  menu  with  too  few  item  lines  to  be  useful.  Figure  37-5  shows 
how  the  Baud  rate  pop-up  menu  from  Figure  37-4  would  appear  if  it  had  been  defined  as  a 
type2  pop-up  menu. 
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■   Figure  37-5     Type  2  pop-up  menu 


9600 


By  dragging  over  the  scroll  indicator,  the  user  can  eventually  scroll  all  menu  items  that  will 
fit  on  the  screen  into  view,  regardless  of  menu  proximity  to  top  or  bottom  of  screen. 

How  to  use  pop-up  menus 

Your  application  can  define  pop-ups  in  two  ways:  either  as  controls  or  menus. 

If  your  application  defines  its  pop-ups  as  controls,  using  the  NewControi2  Control 
Manager  tool  call,  then  drawing,  updating,  resizing,  and  tracking  will  all  be  handled  by 
TaskMaster  and  TrackControi  automatically.  TaskMaster  will  also  deal  with  any 
keystroke  equivalents  you  have  defined.  See  Chapter  28,  "Control  Manager  Update,"  for 
details  on  how  to  create  a  pop-up  control  template  and  invoke  NewControi2. 

If,  on  the  other  hand,  your  application  defines  its  pop-ups  as  menus,  it  gains  flexibility 
but  has  more  responsibility.  Your  application  must  draw  the  pop-up  box  and  title, 
highlight  the  title,  recognize  mouse-down  events  in  the  pop-up  box  or  title,  and  change 
the  current  entry  in  response  to  user  choices.  Your  application  must  also  deal  with 
keystroke  equivalents.  Once  your  program  detects  a  mouse-down  event  inside  the  Pop- 
up box  or  title,  it  must  call  PopupMenuSeiect  to  display  the  menu  and  track  the  mouse. 
This  call  returns  the  item  ID  of  the  selected  item  (0  if  none  selected).  Your  program  can 
use  this  item  ID  to  determine  which  item  was  selected.  Your  program  must  pass  this  item 
ID  to  PopupMenuSeiect  the  next  time  the  user  clicks  in  the  pop-up. 
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♦  Note:  When  you  create  a  pop-up  control  with  NewControi2,  calling  setMitem, 
SetMItem2,  SetMItemName,  SetMItemName2,  SetMItemStyle, 
setMenuTitie  or  setMenuTitie2  does  not  change  the  appearance  of  the  pop-up 
until  the  pop-up  is  redrawn.  If  your  application  changes  the  pop-up  title,  the  system 
does  not  change  the  control  rectangle  to  account  for  a  length  change.  To  resize  the 
control  rectangle,  your  program  must  dispose  of  the  existing  control  and  create  a  new 
one  with  NewControl2. 

Table  37-1  lists  the  Menu  Manager  routines  that  work  with  pop-up  menus.  Refer  to  the  call 
descriptions  in  either  the  Toolbox  Reference  or  m  this  chapter  for  details  on  each  call. 


■  Table  37-1      Menu  Manager  calls  that  work  with  pop-up  menus 


CalcMenuSize 

CheckMItem 

CountMItems 

DeleteMItem 

DisableMItem 

EnableMItem 

GetMenuFlag 

GetMenuTitle 

GetMHandle 

GetMItem 

GetMIteinFlag 

GetMItemMark 

GetMItemStyle 

GetMTitleWidth 

InsertMItem 

SetMenuBar 

SetMenuFlag 

SetMenuID 

SetMenuTitie 

SetMenuTitle2 

SetMitem 

SetMItem2 

SetMItemBlink 
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SetMItemFlag 

SetMItemMark 

SetMItemName 

SetMIteinName2 

SetMItemStyle 

SetMTitleWidth 

Each  of  the  routines  listed  in  Table  37-1  operate  on  the  current  menu  bar.  If  your 
application  defined  its  pop-ups  using  NewControi2,  then  it  must  set  the  pop-up  to  be 
the  current  menu,  by  issuing  the  setMenuBar  call  and  specifying  the  control  handle  for 
the  pop-up  as  input. 

If  your  application  uses  PopUpMenuSeiect,  rather  than  NewControi2,  then  it  must 
insert  the  pop-up  menu  into  the  current  menu  bar  by  calling  insertMenu,  issue  the 
desired  Menu  Manager  tool  calls,  then  remove  the  pop-up  menu  from  the  menu  bar  by 
calling  DeieteMenu.  Your  program  passes  the  handle  to  the  pop-up  menu  to  each  of 
these  routines. 


37-14 


Apple  IlGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


New  Menu  Manager  data  structures 

The  new  Menu  Manager  calls  allow  you  to  define  menus  using  templates,  analogous  to  the 
templates  used  by  the  NewControi2  Control  Manager  tool  call,  which  can  then  be  stored 
in  fbced  memory,  in  allocated  memory  referenced  by  handle,  or  in  resources.  When  using 
any  of  these  new  calls,  your  program  must  specify  the  input  data  according  to  these 
templates. 


♦  Note:  Any  strings  referenced  in  these  data  structure  descriptions  are  Pascal  strings. 
Note  as  well  that  ail  flag  bit  definitions  are  backward  compatible.  That  is,  no  existing 
bits  have  been  redefined.  In  addition,  note  that  the  menuFiag  field  is  now  defined 
as  a  word,  rather  than  a  byte.  The  byte  following  the  old  menuFiag  byte,  menuRes, 
was  never  used,  and  has  been  collapsed  into  menuFiag. 


Menu  item  template 

Figure  37-'6  shows  the  template  that  defines  the  characteristics  of  a  menu  item.  Use  it  with 
new  Menu  Manager  calls  that  require  menu  item  templates. 


■   Figure  37-6     Menu  item  template 


$0A 


—           version  — 

Word— Version  number  for  template;  must  be  set  to  0 

—  itemlD 

Word— Menu  item  ID 

itemChar 

Byte— Primary  keystroke  equivalent  character 

ItemAltChar 

Byte— Alternate  keystroke  equivalent  character 

—  itemCheck 

Word— Charaaer  code  for  checked  items 

—  IteraFlag 

Word— Menu  item  flag  word 

—  IteraTltleRef 

Long— Reference  to  item  title  string 

Identifies  the  version  of  the  menu  item  template.  The  Menu  Manager 
uses  this  field  to  distinguish  between  different  revisions  of  the  menu 
item  template.  Must  be  set  to  0. 
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itemID 


Unique  identifier  for  the  menu  item.  See  Chapter  13,  "Menu  Manager," 
in  the  Toolbox  Reference  for  information  on  valid  values  for  itemiD. 


itemChar,  itemAltChar 

These  fields  define  the  keystroke  equivalents  for  the  menu  item.  The 
user  can  select  the  menu  item  by  pressing  the  Command  key  along  v/ith 
the  key  corresponding  to  one  of  these  fields.  Typically,  these  fields 
contain  the  upper  and  lower  case  ASCII  codes  for  a  particular 
character.  If  you  only  have  a  single  key  equivalence,  set  both  fields 
with  that  value. 


itemCheck 


itemFlag 


titleRefType 


Reserved 

shadow 


outline 


Reserved 
disabled 


divider 


XOR 


Reserved 
underline 


Defines  the  character  to  be  displayed  next  to  the  item  when  it  is 
checked. 

Bit  flags  controlling  the  display  attributes  of  the  menu  item.  Valid 
values  for  itemFlag  are: 

bits  14-15  Defines  the  type  of  reference  in  itemiitieRef : 

00  -  Reference  is  pointer 

01  -  Reference  is  handle 

10  -  Reference  is  resource  ID 

11  -  Invalid  value 
bit  13       Must  be  set  to  0 

bit  12       Indicates  item  shadowing: 

0  -  No  shadow 

1  -  Shadow 

bit  11       Indicates  item  outlining 

0  -  Not  outlined 

1  -  Outlined 
bits  8-10    Must  be  set  to  0 

bit  7         Enables  or  disables  the  menu  item: 

0  -  Item  enabled 

1  -  Item  disabled 

bit  6         Controls  drawing  divider  below  item: 

0  -  No  divider  bar 

1  -  Divider  bar 

bit  5         Controls  how  highlighting  is  performed: 

0  -  Do  not  use  XOR  to  highlight 

1  -  Use  XOR  to  highlight  item 
bits  3-4     Must  be  set  to  0 

bit  2         Controls  item  underlining: 

0  -  Do  not  underline  item 

1  -  Underline  item 
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italic  bit  1         Indicates  wliether  item  is  italicized 

0  -  Not  italicized 

1  -  Italicized 

bold  bit  0         Indicates  whether  item  is  drawn  bold: 

0  -  Not  bold 

1  -  Bold 

itemTitieRef    Reference  to  title  string  for  menu  item.  The  titieRef  Type  bits  in 
iteitiFiag  indicate  whether  itemTitieRef  contains  a  pointer,  a 
handle,  or  a  resource  ID,  If  itemTitieRef  is  a  pointer,  then  the  title 
string  must  be  a  Pascal  string.  Otherwise,  the  Menu  Manager  can 
retrieve  the  string  length  from  control  information  in  die  handle. 
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Menu  template 

Figure  37-7  shows  the  menu  template,  which  defines  the  characteristics  of  a  menu, 
including  its  menu  item  references.  Use  it  with  new  Menu  Manager  calls  that  require  menu 
templates. 

■   Figure  37-7     Menu  template 


$00  -       version        -  Word—Version  number  for  template;  Hiust  be  set  to  0 

$02  _        menuiD         -  Word— Menu  ID 

$04  _      menuFiag        -  Word— Menu  flag  word 


$06  - 

menuTltleRef      -H  Long— Reference  to  menu  title  String 


$0A 

•      ItemRefArray       •  n  Longs— References  to  menu  items 


version 


Identifies  the  version  of  the  menu  template.  The  Menu  Manager  uses 
this  field  to  distinguish  between  different  revisions  of  the  template. 
Must  be  set  to  0. 


menuID 


Unique  identifier  for  the  menu.  See  Chapter  13,  "Menu  Manager,"  in  the 
Toolbox  Reference  for  information  on  valid  values  for  menuiD. 


menuFlag 


Bit  flags  controlling  the  display  and  processing  attributes  of  the  menu. 
Valid  values  for  menuFiag  are: 


titleRefType 


bits  14-15  Defines  the  type  of  reference  in  menuTitieRef : 


00  -  Reference  is  pointer 

01  -  Reference  is  handle 

10  -  Reference  is  resource  ID 

11  -  Invalid  value 
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itemRef Type 


Reserved 

alwaysCallmChoose 


bits  12-13  Defines  the  type  of  reference  in  each  entry  of 

itemRef  Array  (all  array  entries  must  be  of  the  same 
type): 

00  -  References  are  pointers 

01  -  References  are  handles 

10  -  References  are  resource  IDs 

11  -  Invalid  value 
bits  9-11    Must  be  set  to  0 


bits 


disabled 
Reserved 

XOR 

custom 

allowCache 

Reserved 
menuTitleRef 


itemRef Array 


bit? 


bit  6 
bit  5 


bit  4 


bit  3 


bits  0-2 


Causes  the  Menu  Manager  to  call  a  custom  menu 
defProc  mChoose  routine  even  when  the  mouse  is  not 
in  the  menu  rectangle  (supports  tear-off  menus): 

0  -  Do  not  always  call  mChoose  routine 

1  -  Always  call  mChoose  routine 
Enables  or  disables  the  menu: 

0  -  Menu  enabled 

1  -  Menu  disabled 
Must  be  set  to  0 

Controls  how  selection  highlighting  is  performed: 

0  -  Do  not  use  XOR  to  highlight 

1  -  Use  XOR  to  highlight  item 

Indicates  whether  custom  or  standard  menu: 

0  -  Standard  menu 

1  -  Custom  menu 
Controls  menu  caching: 

0  -  Do  not  cache  menu 

1  -  Menu  caching  allowed 
Must  be  set  to  0 


Reference  to  title  string  for  menu.  The  titieRef  Type  bits  in 
menuFiag  indicate  whether  menuTitleRef  contains  a  pointer,  a 
handle,  or  a  resource  ID.  If  menuTitleRef  is  a  pointer,  then  the  title 
string  must  be  a  Pascal  string.  Otherwise,  the  Menu  Manager  can 
retrieve  the  string  length  from  control  information  in  the  handle. 

Array  of  references  to  the  menu  items  for  the  menu.  The 
itemRef  Type  bits  in  menuFiag  indicate  whether  the  entries  in  the 
array  are  pointers,  handles,  or  resource  IDs.  Note  that  all  array  entries 
must  contain  the  same  reference  type.  The  last  entry  in  the  array  must 
be  set  to  $00000000. 
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Menu  bar  template 

Figure  37-8  shows  the  menu  bar  template,  which  defines  the  characteristics  of  a  menu  bar, 
including  its  menu  references.  Use  it  with  new  Menu  Manager  calls  that  require  menu  bar 
templates. 


Figure  37-8     Menu  bar  template 


$00 

—        version  — 

Word— Version  number  for  template;  must  be  set  to  0 

$02 

—       menuFlag  — 

Word— Menu  bar  flag  word 

$04 

menuRef Array 

n  Longs— References  to  menus 

version 


menuBarFlag 


menuRef Type 


Reserved 


menuRef Array 


Identifies  the  version  of  the  menu  bar  template.  The  Menu  Manager 
uses  this  field  to  distinguish  between  different  revisions  of  the 
template.  Must  be  set  to  0. 

Bit  flags  controlling  the  display  and  processing  attributes  of  the  menu 
bar.  Valid  values  for  menuBarFlag  are: 

bits  14-15  Defines  the  type  of  reference  in  each  entry  of 

menuRef  Array  (all  array  entries  must  be  of  the  same 
type): 

00  -  References  are  pointers 

01  -  References  are  handles 

10  -  References  are  resource  IDs 

11  -  Invalid  value 
bits  0-13    Must  be  set  to  0 

Array  of  references  to  the  menus  for  the  menu  bar.  The  menuRef  Type 
bits  in  menuBarFlag  indicate  whether  the  entries  in  the  array  are 
pointers,  handles,  or  resource  IDs.  Note  that  all  array  entries  must 
contain  the  same  reference  type.  The  last  entry  in  the  array  must  be  set 
to  $00000000. 
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New  Menu  Manager  calls 

The  following  sections  discuss  the  various  new  Menu  Manager  tool  calls  in  alphabetical 
order  by  call  name. 

GetPopUpDefProc  $3B0F 

Returns  a  pointer  to  the  control  definition  procedure  for  pop-up  menus.  Your  application 
should  not  issue  this  call. 

The  system  issues  this  call  during  Control  Manager  start  up  processing  in  order  to  obtain 
the  address  of  the  pop-up  menu  definition  procedure. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


-    defProcPtr  - 


Long— Pointer  to  control  procedure 


<— SP 


Errors 


None 


C 


extern  pascal  Pointer  GetPopUpDefProc () ; 
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HideMenuBar  $450F 

Hides  the  system  menu  bar,  by  adding  tlie  menu  bar  to  the  deslctop  region.  This  call  sets 
the  invisible  flag  for  the  menu  bar,  resets  scan  lines  2  through  9  (which  had  been  changed 
to  correctly  display  the  colors  of  the  Apple  logo),  and  refreshes  the  desktop.  The  system 
ignores  all  subsequent  calls  to  DrawMenuBar  or  FiashMenuBar,  since  the  menu  bar  is 
invisible.  Use  the  showMenuBar  call  to  make  the  menu  bar  visible  again. 

Parameters 

Stack  before  call 

Previous  contents 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


None 


C 


extern  pascal  void  HideMenuBar ()  ; 
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InsertMItem2  $3F0F 

Inserts  a  menu  item  into  a  menu  after  a  specified  menu  item  or  at  the  top  of  the  menu. 
This  call  accepts  a  menu  item  template  for  its  input  specification. 

Parameters 

Stack  before  call 


Prmous  contents 


refDescriptor 


-  menuItmTReJ  - 


insertAfter 


menuNum 


Stack  after  call 


Word— Defines  type  of  reference  in  menuItemTRef 
Long— Reference  to  menu  item  template 
Word— ID  of  item  after  which  to  insert  this  item 
Word— ID  of  menu  into  which  to  insert  item 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  InsertMItem2 (refDescriptor, 
menuItemTRef,  insertAfter,  menuNum) ; 

Word  refDescriptor,   insertAfter,  menuNum; 

Long  menuItemTRef; 

refDescriptor       Indicates  the  type  of  reference  stored  in  menuTRef.  Valid  values  are; 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 

insertAfter  Specifies  ID  of  item  after  which  the  new  item  is  to  be  inserted.  In 

order  to  insert  the  new  item  at  the  top  of  the  menu,  set  this  field  to  0. 
To  insert  at  the  end,  set  this  field  to  $FFFF. 
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NewMenu2  $3£0F 

Allocates  space  for  a  menu  list  and  its  items.  This  call  accepts  a  menu  template  for  its 
input  specification. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


re/Descriptor 


menuTRef 


Stack  after  call 


Long— Space  for  result 

Word— Defines  type  of  reference  in  menuTRef 
Long — Reference  to  menu  template 
<— SP 


Previous  contents 


■  menuBarHandle 


Errors 
C 


Long — Handle  for  new  menu 


<— SP 


None 

extern  pascal  Long  NewMenu2 (refDescriptor, 
menuTRef) ; 


Word  refDescriptor; 
Long  menuTRef; 


refDescriptor       Indicates  the  type  of  reference  stored  in  menuTRef  Valid  values  are; 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 
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NewMenuBar2  $430F 

Creates  a  default  menu  bar  with  no  menus.  This  call  accepts  a  menu  bar  template  for  its 
input  specification, 

The  upper-left  comer  of  the  default  menu  bar  matches  the  port,  and  is  as  wide  as  the 
screen.  The  bar  is  13  pbcels  high. 

Note  that  passing  a  NIL  value  for  the  windowPtr  parameter  creates  a  menu  bar  that  is  not 
inside  a  window,  but  does  not  automatically  replace  the  current  menu  bar.  In  order  to 
create  a  new  system  menu  bar  and  make  it  current,  you  must  issue  the  following  tool  calls: 
NewMenuBar2 {) 

SetSysBar  /*  use  menuBarHandle  from  NewMenuBar2  */ 

SetMenuBar (NIL) 

Parameters 

Stack  before  call 


Previous  contents 


Space 


reJDescriptor 


-  menuBarTRef 


-    windowPtr  - 


Long— Space  for  result 

Word— Defines  type  of  reference  in  menuBarTRef 
Long— Reference  to  menu  bar  template 

Long— Pointer  to  port  for  window;  NIL  for  system  menu  bar 
<— SP 


Stack  after  call 


Previous  contents 


-  menuBarHandle 


Errors 
C 


None 


Long— Handle  foMew  menu  bar 
<— SP 


extern  pascal  Long  NewMenuBar2 (refDescriptor, 
menuBarTRef,  windowPtr) ; 
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Word  refDescriptor; 
Long  menuBarTRef ; 

Pointer  windowPtr; 

refDescriptor       Indicates  the  type  of  reference  stored  in  menuBarTRef.  Valid  values 
are: 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 
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PopUpMenuSelect  $3C0F 

Draws  highlighted  titles  and  handles  user  interaction  when  the  user  clicks  on  a  pop-up 
menu. 

You  specify  the  pop-up  with  the  handle  returned  by  NewMenu  or  NewMenu2. 


♦  Note:  The  system  draws  the  pop-up  menu  into  the  port  that  is  active  at  the  time  you 
issue  the  PopUpMenuSeiect  call.  The  menu  is  constrained  by  the  intersection  of  the 
port  rectangle,  the  visible  region,  and  the  clip  region.  By  altering  any  of  these  you  can 
change  the  constraints  on  the  menu. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


selection 


currentLeft 


currentTop 


flag 


-  menuHandle  - 


Stack  after  call 


Word— Space  for  result  (Item  ID) 

Word— Item  ID  of  current  menu  selection 

Word— Global  coordinate  value  of  left  edge  of  pop-up  menu 

Word— Global  coordinate  value  of  top  of  current  selection 

Word— Flag  word  for  call 

Long— Menu  handle 

<— SP 


Previous  contents 


itemID 


Word— Item  ID  of  new  selection  (0  if  none) 
<— SP 


Errors 


None 
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C  extern  pascal  Word  PopUpMenuSelect (selection, 

currentLeft,   currentTop,  flag, 
menuHandle) ; 

Word  selection,  currentLeft,  currentTop,  flag; 

Long  menuHandle; 

selection  Defines  the  current  selection  in  the  menu.  Set  to  0  if  no  item  is 

currently  selected.  The  initial  value  is  the  default  value  for  the  menu, 
and  is  displayed  in  the  pop-up  rectangle  of  "unpopped"  menus.  You 
specify  an  item  by  its  ID,  that  is,  its  relative  position  within  the  array 
of  items  for  the  menu  (see  Chapter  37,  "Menu  Manager  Update,"  for 
information  on  the  layout  and  content  of  the  pop-up  menu  template). 
If  you  pass  an  invalid  item  ID  then  no  item  is  displayed  in  the  pop-up 
rectangle. 

currentLeft,  currentTop 

Define  the  left  edge  of  the  pop-up  and  the  top  of  the  current 
selection,  global  coordinates. 

ftag  Flag  word  for  the  tool  call.  Bits  are  defined  as  follows: 

Reserved  bits  7-15    Must  be  set  to  0 

type2  bit  6         Indicates  whether  pop-up  is  type  1  or  type2: 

0  -  Type  1  menu  (no  white  space  added) 

1  -  Type  2  menu  (white  space  added) 
Reserved               bits  0-5     Must  be  set  to  0 

menuHandle       The  handle  of  the  pop-up  menu.  The  Menu  Manager  retumed  this  value 
to  your  application  from  NewMenu  or  NewMenu2. 
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SetMenuTitle2  $400F 

Specifies  the  title  for  a  menu.  This  call  accepts  a  reference  to  the  title  string  that  can  be  a 
pointer,  handle,  or  resource  ID. 

Parameters 

Stack  before  call 


Previous  contents 


re/Descriptor 


titleRef 


menuNum 


Stack  after  call 


Word— Defines  type  of  reference  in  titleRef 
Long— Reference  to  title  string  for  menu 
Word— ID  of  menu  to  receive  titie 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  SetMenuTitle2 (refDescriptor, 
titleRef,  menuNum) ; 


Word 
Long 


refDescriptor,  menuNiira; 
inenuItemTRef  ; 


repescriptor       Indicates  the  type  of  reference  stored  in  titleRef.  Valid  values  are: 


0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 
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SetMItem2  $4lOF 

Specifies  the  name  for  a  menu  item.  Tliis  call  accepts  a  menu  item  template  for  its  input 
specification. 

Parameters 

Stack  before  call 


Previous  contents 


reJDescriptor 


-  menuItemTRef  - 


menultem 


Stack  after  call 


Word— Defines  type  of  reference  in  menuItemTRef 

Long— Reference  to  menu  item  template 

Word— ID  of  item  to  be  changed 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  SetMItem2 (ref Descriptor, 
menuItemTRef,  menultem) ; 

Word  refDescriptor,  menultem; 

Long  menuItemTRef; 

re/Descriptor       Indicates  the  type  of  reference  stored  in  menuItemTRef.  Valid  values 
are: 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 

menultem  Specifies  the  menu  item  to  be  changed.  Note  that  you  can  change  the 

item  ID  by  specifying  a  different  item  number  in  the  menu  item 
template.  The  Menu  Manager  will  apply  the  item  ID  from  the  template 
to  the  item  to  be  changed. 
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SetMItemName2  $420F 

Specifies  the  name  of  a  menu  item  .  This  call  accepts  a  reference  to  a  title  string  that  can 
be  a  pointer,  handle,  or  resource  ID. 

Parameters 

Stack  before  call 


Previous  contents 


re/Descriptor 


titleRef 


menultem 


Stack  after  call 


Word— Defines  type  of  reference  in  titleRef 

Long— Reference  to  menu  item  title 

Word— ID  of  item  to  be  changed 
<— SP 


Previous  contents 


Errors 
C 


rejDescriptor 


None 


<— SP 


extern  pascal  void  SetMItemName2 (ref Descriptor, 
titleRef,  menultem) ; 

Word  refDescriptor,  menuNum; 

Long  titleRef; 

Indicates  the  type  of  reference  stored  in  titleRef.  Valid  values  are: 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 
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ShowMenuBar  $460F 

Reveals  the  system  menu  bar,  by  subtracting  the  menu  bar  from  the  desktop  region.  This 
call  also  resets  the  invisible  flag  for  the  menu  bar,  resets  scan  lines  2  through  9  (to 
correctly  display  the  colors  of  the  Apple  logo),  and  draws  the  menu.  Use  the 
HideMenuBar  call  to  make  the  menu  bar  invisible. 

Parameters 

Stack  before  call 

Previous  contents 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


None 


C 


extern  pascal  void  ShowMenuBar () ; 
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Chapter  38  MIDI  Tool  Set 


This  chapter  documents  the  MIDI  Tool  Set.  This  is  a  new  tool  set;  it  was 
not  documented  in  the  Apple  IlGS  Toolbox  Reference. 
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About  the  MIDI  Tool  Set 

The  Apple  IIGS  MIDI  Tool  Set  provides  a  software  interface  between  the  Apple  IlGS  and 
external  synthesizers  and  other  musical  equipment  that  accepts  the  Musical  Instrument 
Digital  Interface  (MIDI)  protocol.  The  MIDI  Tool  Set  has  the  following  key  attributes: 

■  Hardware  independence 

The  MIDI  Tool  Set  is  hardware-independent.  It  uses  a  separately  loaded  device  driver 
to  communicate  with  the  hardware  interface  that  connects  the  Apple  IIGS  to  an 
external  MIDI  device.  This  driver-based  design  frees  applications  from  referencing  the 
specifics  of  the  MIDI  hardware  interface.  Applications  that  use  the  MIDI  Tool  Set  can 
therefore  run  on  Apple  IIGS  systems  with  different  MIDI  interfaces. 

■  Intemipt-driven  operation 

The  MIDI  Tool  Set  is  interrupt-driven  and  can  transfer  MIDI  data  in  the  background 
while  other  tasks  take  place  in  the  foreground,  For  example,  it  is  possible  to  write  an 
application  that  enables  a  user  to  edit  MIDI  data  while  simultaneously  playing  a 
sequence.  MIDI  applications  that  use  the  tool  set  need  not  provide  interrupt  handlers 
since  they  are  provided  by  the  MIDI  Tool  Set. 

■  Accurate  dock 

The  MIDI  Tool  Set  provides  a  high-speed,  high-resolution  clock.  If -an  application 
needs  precise  timing,  it  can  use  the  MIDI  Tool  Set  clock  to  provide  time-stamps 
accurate  to  within  76  microseconds.  The  clock  uses  one  of  the  Digital  Oscillator 
Chip  (DOC)  generators  and  the  first  256  bytes  of  DOC  RAM.  When  the  clock  is  not  in 
use,  the  MIDI  Tool  Set  releases  the  DOC  generator  and  RAM.  See 
Chapter  47,  "Sound  Tool  Set  Update,"  for  more  information  about  the  Digital 
Oscillator  Chip. 

■  Fast  response 

The  tool  set  automatically  polls  incoming  MIDI  data,  and  receives  the  data  without 
loss  at  speeds  up  to  one  byte  per  320  microseconds— as  long  as  interrupts  are  never 
disabled  for  more  than  270  microseconds.  If  your  application  must  disable  interrupts 
for  longer  than  this  interval,  you  can  use  the  MidiinputPoii  vector  to  retrieve 
incoming  data  explicidy. 

■  Multiple  formats 

The  tool  set  supports  two  input  and  output  formats.  When  the  application  retrieves 
MIDI  data  in  raw  mode,  it  receives  the  data  bytes  exactly  as  they  appear  in  the  input 
stream,  but  with  length  and  time-stamp  data  added.  In  packet  mode,  the  MIDI  Tool 
Set  expects  to  receive  MIDI  data  packets,  but  will  perform  some  additional  cleanup 
to  make  those  packets  complete. 
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■  Error  checks 

The  MIDI  Tool  Set  provides  error-checking  and  reports  a  variety  of  error  conditions, 
including  reception  of  MIDI  packets  with  an  incorrect  number  of  data  bytes. 

■  Real-time  and  background  commands 

The  MIDI  Tool  Set  can  report  real-time  commands  to  an  application  immediately.  This 
feature  enables  the  application  to  process  real-time  commands  as  they  occur,  for 
interactive  control  of  musical  instruments. 

■  Intelligent  NoteOff  commands 

The  tool  sef  s  NoteOff  commands  can  turn  off  all  notes  that  are  playing  or  only  those  it 
has  turned  on.  They  can  do  this  on  all  channels  or  only  on  specified  channels. 

■  Variable  clock  frequency 

You  can  change  the  time  base  for  MIDI  timestamps,  thereby  varying  the  tempo  of 
played  data  (see  the  description  of  the  miSetFreq  function  of  the  Midiciock  tool 
call  later  in  this  chapter  for  more  information). 

■  User  definable  service  routines 

You  can  enhance  the  functionality  provided  by  the  MIDI  Tool  Set  by  providing  your 
own  service  routines.  The  MIDI  Tool  Set  calls  these  routines  under  a  variety  of  defined 
circumstances.  See  "MIDI  Tool  Set  service  routines"  later  in  this  chapter  for  more 
information, 

♦  Note:  The  Note  Synthesizer,  the  Note  Sequencer,  and  the  MIDI  Tool  Set  refer  to  the 
software  tools  provided  with  the  Apple  IIGS,  not  to  any  separate  instrument  or 
device.  The  MIDI  tools  are  software  tools  for  use  in  controlling  external  instruments, 
which  may  be  connected  through  a  MIDI  interface  device. 
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Using  the  MIDI  Tool  Set 

This  section  describes  the  basic  steps  involved  in  using  the  MIDI  Tool  Set  to  interact  with 
external  musical  instruments.  Following  the  initial  overview  discussion  are  several  code 
examples,  demonstrating  techniques  for  performing  many  key  MIDI  Tools  functions. 

Figure  38-1  illustrates  some  of  the  relationships  between  a  typical  MIDI  application,  the 
MIDI  Tool  Set,  MIDI  device  drivers,  and  a  MIDI  interface  card. 


384     Apple  IIGS  Toolbox  Reference,  Volume  3 


/^ple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Figure  38-1     MIDI  application  environment 
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Before  using  the  MIDI  Tool  Set,  you  must  install  the  tool  set  and  its  associated  drivers 
using  the  Installer  utility. 
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To  use  the  MIDI  Tool  Set,  you  must  first  start  it  up  with  the  Midistartup  call.  Then  you 
must  load  a  MIDI  device  driver  by  using  the  Midioevice  call.  The  tool  set  loads  the 
driver  separately  so  that  its  operation  is  independent  of  the  particular  MIDI  interface  that 
connects  the  Apple  IIGS  to  the  external  MIDI  instrument. 

MIDI  device  drivers  are  normally  found  in  the  VSYSTEM/DRIVERS  directory,  and  end  with 
the  suffix  .MIDI.  Apple  currently  supplies  the  APPLE.MIDI  and  CARD6850.MIDI  drivers; 
the  first  driver  supports  the  Apple  MIDI  Interface,  and  the  second  supports  plug-in  6850- 
based  Asynchronous  Communications  Interface  Adapter  (ACIA)  cards. 

After  the  application  loads  the  MIDI  device  driver,  it  must  make  the  Midicontroi  call 

to  allocate  input  and  output  buffers  for  MidiReadPacket  and  MidiWritePacket 
calls.  Note  that  if  the  application  never  calls  MidiReadPacket,  it  need  not  allocate  an 
input  buffer,  and  if  it  never  calls  MidiwritePacket,  it  need  not  allocate  an  output 
buffer. 

The  MIDI  Tool  Set  is  now  ready  to  send  or  receive  MIDI  data.  However,  the  application 
must  explicitly  start  the  MIDI  input  and  output  processes,  using  the  appropriate  options 

of  the  Midicontroi  tOOl  Call. 

The  application  can  start  or  stop  MIDI  data  transfer  at  any  time.  Once  started,  the  input 
and  output  processes  continue  without  intervention  until  stopped  by  the  application. 
They  run  in  the  background  so  that  other  processes,  such  as  interaction  with  the  user,  can 
run  unimpeded  in  the  foreground.  The  tool  set  enables  the  programmer  to  switch  the 
processes  on  or  off  at  any  time  because  MIDI  data  transfer  incurs  considerable  processor 
overhead,  and  a  programmer  might  want  to  disable  it  under  some  circumstances  to 
improve  the  application's  performance  on  other  tasks. 

The  MIDI  input  process  fills  the  MIDI  Tool  Sef  s  input  buffer  with  data  packets  as  they 
arrive.  The  application  must  periodically  retrieve  the  data  from  the  buffer  by  making  calls 
to  MidiReadPacket.  Similarly,  the  MIDI  output  process  transmits  the  data  placed  in 
the  tool  sefs  output  buffer  by  application  with  calls  to  MidiwritePacket.  The  Apple 
IIGS  can  simultaneously  send  and  receive  MIDI  data  packets. 

When  you  use  the  Midiciock  call  to  start  the  MIDI  Tool  Sefs  clock,  the  tool  set  begins 
stamping  each  data  packet  with  a  time  value  it  retrieves  from  its  clock  process.  This 
clock  is  actually  a  DOC  generator  that  the  MDI  Tool  Set  allocates  with  the  Note 
Synthesizer  AiiocGen  call.  Start  the  MIDI  clock  before  starting  the  input  process, 
because  the  Midiciock  function  disables  interrupts  long  enough  to  interfere  with 
correct  reception  of  MIDI  data. 
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The  clock  is  very  fast;  a  tick  occurs  every  76  microseconds  at  the  default  settings.  MIDI 
data  packets  receive  a  time-stamp  consisting  of  the  value  of  the  clock  when  they  are 
received.  MidiwritePacket  receives  a  packet  with  a  time-stamp  attached  and  writes 
it  to  the  output  buffer,  and  the  MIDI  Tool  Set  transfers  the  packet  only  when  the  current 
value  of  the  clock  is  greater  than  the  output  data's  time-stamp. 

If  the  clock  is  stopped,  MIDI  input  data  receive  time-stamps  equal  to  the  value  of  the 
stopped  clock,  and  only  MIDI  data  with  time-stamps  less  than  the  value  of  the  stopped 
clock  can  be  sent. 

If  you  want  to  read  and  write  MIDI  packets  in  real  time,  in  response  to  user  events,  you  do 
not  need  the  MIDI  clock. 

You  can  start  or  stop  the  MIDI  clock  or  the  input  and  output  processes  at  any  time,  so 
that  you  can  budget  processor  resources  intelligently.  The  input,  output,  and  clock 
processes  consume  a  great  deal  of  processor  time,  and  so  limit  the  processing  power 
available  to  tasks  that  execute  during  their  operation. 


Tool  dependencies 

The  MIDI  Tool  Set  uses  Note  Synthesizer  calls  to  allocate  a  DOC  generator  for  its  clock.  If 
your  application  does  not  use  the  MIDI  Tool  Set  clock,  you  need  not  start  up  the  Note 
Synthesizer  to  use  the  MIDI  Tool  Set.  If  your  application  is  not  using  the  MIDI  Tool  Set 
clock  or  MidiinputPoii,  then  it  can  start  up  and  shut  down  the  Note  Synthesizer  as 
needed,  but  the  Note  Synthesizer  must  be  started  up  if  you  use  the  MIDI  clock  or  the 

MidiinputPoii  veaor. 

The  Sound  Tools  must  be  started  to  use  the  MIDI  tools. 

Refer  to  Chapter  51,  "Tool  Locator  Update,"  for  information  about  the  specific  version 
requirements  the  MIDI  Tool  Set  has  for  other  tool  sets. 


MIDI  packet  format 

MIDI  data  sent  and  received  using  the  MIDI  Tool  Set  must  always  be  formatted  into  valid 
MIDI  Tool  Set  packets.  The  tool  set  handles  this  for  incoming  data;  your  application  must 
format  outgoing  data  according  to  the  packet  layout  described  in  this  section. 
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The  first  2  bytes  of  a  packet  contain  a  byte  count  of  tlie  MIDI  data  in  the  packet,  plus  the 
4-byte  time-stamp.  The  next  4  bytes  are  the  time-stamp,  and  are  equal  to  the  value  of  the 
MIDI  clock  at  the  time  the  packet  was  received.  The  remaining  bytes  are  the  actual  MIDI 
data: 


$00 

—           length  — 

Word— Packa  length  (excluding  length ) 

$02 

tlmestamp 

4  Bytes-^IDI  time-stamp 

$06 

MIDIData 

Array— MIDI  data  (variable  length) 

A  NoteOn  command  might  look  like  this  (in  hex  notation): 

0700  24630300  9040 5C 

The  first  2  bytes  are  the  length  in  bytes  of  the  MIDI  data  packet  plus  the  4-byte 
time-stamp.  In  this  case  the  MIDI  packet  is  3  bytes,  so  the  length  value  is  7.  The  next  4 
bytes  contain  the  time-stamp,  and  the  MIDI  data  follow. 

The  result  of  a  MidiReadPacket  call  on  this  packet  is  9— the  7  bytes  counted  in  the 
length  word  plus  the  2  bytes  of  the  length  word  itself. 

If  the  current  input  mode  is  MIDI  packet  mode,  the  first  byte  of  the  MIDI  data  is  always  a 
MIDI  status  byte.  If  a  received  MIDI  packet  does  not  contain  a  valid  status  byte,  the 
MIDI  Tool  Set  inserts  the  current  status  at  the  beginning  of  the  packet. 
MidiReadPacket  never  retums  real-time  commands  in  packet  mode;  they  are  always 
passed  to  the  real-time  command  routine  installed  by  Midicontroi.  See  "MIDI  Tool  Set 
service  routines"  later  in  this  chapter  for  more  information. 

In  raw  mode  the  MIDI  data  are  returned  to  the  application  just  as  they  are  received  from 
the  MIDI  interface.  The  MIDI  protocol  allows  MIDI  devices  to  omit  the  status  byte  unless 
it  has  changed  from  its  last  value.  The  status  byte  may  appear  anywhere  in  the  stream 
because  it  may  be  received  only  when  it  changes.  MIDI  devices  may  also  omit  the  $F7 
value  at  the  end  of  a  MIDI  System  Exclusive  command;  the  $F7  value  always  appears  at  the 
end  of  a  System  Exclusive  command  in  packet  mode,  but  not  necessarily  in  raw  mode. 
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In  raw  mode,  the  maximum  number  of  MIDI  data  bytes  that  MidiReadPacket  passes  to 
the  application  is  4.  Therefore,  the  longest  packet  it  can  pass  is  10  bytes  in  length— 2 
length  bytes,  4  time-stamp  bytes,  and  4  MIDI  data  bytes.  In  packet  mode.  System 
Exclusive  packets  may  be  of  any  length. 

MidiReadPacket  also  returns  real-time  commands  in  raw  mode  unless  a  real-time  vector 
is  installed  See  "MidiControi"  later  in  this  chapter  for  more  information. 


MIDI  Tool  Set  service  routines 

Your  program  can  contain  service  routines  that  the  MIDI  Tool  Set  will  invoke  under  certain 
defined  circumstances.  By  providing  these  service  routines,  you  can  tailor  the 
functionality  of  the  MIDI  Tool  Set  to  fit  your  particular  needs.  The  MIDI  Tool  Set  calls 
these  routines  under  the  following  circumstances 

Real-time  command  routine       Called  when  the  MIDI  Tool  Set  receives  a  MIDI  real-time 

command.  You  set  the  vector  to  this  routine  with  the 
miSetRTVec  function  of  the  MidiControi  tOOl  call. 

Real-time  error  routine  Called  when  the  MIDI  Tool  Set  encounters  an  error 


Output  data  routine 


Input  data  routine 


during  real-time  processing.  You  set  the  vector  to  this 
routine  with  the  misetErrVec  function  of  the 
MidiControi  tOOl  call. 

Called  by  the  MIDI  Tool  Set  to  handle  MIDI  data 
received  during  processing  of  an  mistartinput 
function  request.  You  set  the  vector  to  this  routine 
when  you  issue  the  mistartinput  function  of  the 

MidiControi  tOOl  call. 

Called  by  the  MIDI  Tool  Set  to  obtain  data  to  send 
during  processing  of  an  mistartoutput  function 
request.  You  set  the  vector  to  this  routine  when  you 
issue  the  mistartoutput  function  of  the 
MidiControi  tOOl  call. 


The  following  sections  discuss  each  of  these  service  routines  in  more  detail. 
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Real-time  command  routine 

When  the  MIDI  Tool  Set  receives  MIDI  real-time  commands,  it  calls  this  service  routine. 
The  service  routine  must  not  enable  interrupts,  and  if  it  runs  for  longer  than  300 
microseconds,  it  must  call  the  MIDI  polling  vector  at  least  every  270  microseconds.  The 
only  MIDI  calls  that  the  service  routine  should  make  are  MidiReadPacket  and 
MidiWritePacket. 

Real-time  MIDI  data  are  passed  to  the  service  routine  in  the  low-order  byte  of  a  word  on 
the  stack  above  the  rtl  address.  This  word  must  remain  on  the  stack.  When  the  service 
routine  is  called,  the  data  bank  register  is  set  to  the  value  it  had  when  Midistartup  was 
called,  but  the  direct-page  register  points  to  one  of  the  MIDI  Tool  Set's  direct  pages  and 
must  be  preserved. 

You  set  the  vector  to  this  routine  with  the  misetRTVec  function  of  the  Midicontroi 
tool  call. 

Parameters 

Stack  before  call 


Previous  contents 


MDIData 


-  retumAddress  - 


Word— Low-order  byte  contains  MIDI  real-time  data 
3  Bytes— RTL  address 

<— SP 


Stack  after  call 


Previous  contents 


MDIData 


-  retumAddress  - 


Word— Low-order  byte  contains  MIDI  real-time  data 
3  Bytes— RTL  address 
<— SP 
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Real-time  error  routine 

The  MIDI  Tool  Set  calls  this  routine  in  the  event  of  a  MIDI  real-time  error.  This  service 
routine  must  not  enable  interrupts,  If  it  executes  for  longer  than  300  microseconds,  it 
must  call  the  MIDI  polling  vector  at  least  every  270  microseconds.  It  can  call 
MidiWritePacket  and  MidiReadPacket,  but  no  Other  MIDI  tOOl  calls. 

The  error  is  passed  to  the  service  routine  in  a  word  on  the  stack  above  the  rtl  address. 
This  word  must  remain  on  the  stack.  When  the  service  routine  is  called,  the  data  bank 
register  is  set  to  the  value  it  had  when  Midi  startup  was  called,  but  the  direct  page 
register  points  to  one  of  the  MIDI  Tool  Set's  direct  pages  and  must  be  preserved.  When 
the  MIDI  Tool  Set  invokes  this  routine,  there  is  very  little  space  left  on  the  stack. 

You  set  the  vector  to  this  routine  with  the  miSetErrvec  function  of  the  Midicontroi 
tool  call. 

The  service  routine  may  receive  the  following  error  codes; 


$200A 
$2084 


miClockErr 
miDevNoConnect 


MIDI  clock  wrapped  to  0. 
No  connection  to  MIDI 
interface. 


Parameters 


Stack  before  call 


Previous  contents 


MIDIError 


Word— Error  code 


-  retumAddress  - 


3  Bytes— RTL  address 


<— SP 


Stack  after  call 


Previous  contents 


MIDIError 


Word — Error  code 


-  retumAddress  - 


3  Bytes — rtl  address 


<— SP 
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Input  data  routine 

The  MIDI  Tool  Set  calls  this  routine  during  processing  of  the  mi  start  input  function  of 
the  Midi  Control  tool  Call  when  the  first  packet  is  available  in  a  previously  empty  input 
buffer.  The  service  routine  must  not  enable  interrupts,  and  if  it  runs  for  longer  than  300 
microseconds,  it  must  call  MidiinputPoii  at  least  every  270  microseconds.  The  only 
MIDI  calls  that  the  service  routine  should  make  are  MidiReadPacket  and 
MidiWritePacket. 

When  the  service  routine  is  called,  the  data  bank  register  is  set  to  the  value  it  had  when 
Midistartup  was  called,  but  the  direct  page  register  points  to  one  of  the  MIDI  Tool 
Set" s  direct  pages  and  must  be  preserved.  The  system  will  call  the  service  routine 
immediately  if  a  complete  MIDI  packet  is  available  in  the  input  buffer  when  the 
mistartinput  function  of  the  MidiControi  tool  call  is  made. 

You  set  the  vector  to  this  routine  when  you  issue  the  mistartinput  function  of  the 
MidiControi  tOOl  call. 

Parameters 

Stack  before  call 


PretHoiiS  contents 


-  retumAddress  - 


3  Bytes— RTL  address 
<— SP 


Stack  after  call 


Previous  contents 


-  retumAddress  - 


3  Bytes— RTL  address 
<— SP 
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Output  data  routine 

The  MIDI  Tool  Set  calls  this  routine  during  processing  of  the  mistartoutput  function 
of  the  Midicontroi  tool  call  when  the  output  buffer  becomes  completely  empty.  The 
service  routine  must  not  enable  interrupts,  and  if  it  runs  for  longer  than  300  microseconds, 
it  must  call  the  MIDI  polling  vector  at  least  every  270  microseconds.  The  only  MIDI  calls 
that  the  service  routine  should  make  are  MidiReadPacket  and  MidiwritePacket. 

When  the  service  routine  is  called,  the  data  bank  register  is  set  to  the  value  it  had  when 
Midi  St  art  up  was  Called,  but  the  direct  page  register  points  to  one  of  the  MIDI  Tool 
Set" s  direct  pages  and  must  be  preserved. 

You  set  the  vector  to  this  routine  when  you  issue  the  mistartoutput  function  of  the 

MidiControl  tOOl  call. 

Parameters 

Stack  before  call 


Prmous  contents 


-  retumAddress  - 


Stack  after  call 


Prmous  contents 


-  retumAddress  - 


3  Bytes— RTL  address 
<— SP 


3  Bytes— RTL  address 
<— SP 
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Starting  up  the  MIDI  Tool  Set 

The  Midistartup  call  takes  as  arguments  a  word  containing  the  Memory  Manager  ID 
number  of  the  application  that  is  starting  up  the  tools,  and  a  word  containing  the  address 
of  a  three-page  memory  block  in  bank  zero.  The  three-page  block  is  used  as  the  MIDI 
Tool  Set's  direct-page  area,  and  it  must  be  aligned  on  a  page  boundary. 

/* 

*  StartupTools () 
* 

*  Starts  up  the  MIDI  Tool  Set  and  all  of  the  tools  it 

*  requires.     For  readability,  this  subroutine  is  presented 

*  without  the  error-checking  that  would  normally  be  performed 

*  after  each  tool  is  started  (call?) . 
*/ 


/*  direct  page  use  */ 

#define  DPForSound  0x0000 

#define  DPForMidi  0x0100 

#define  DPForEventMgr  0x0400 

#define  TotalDP  0x0500 


/*  needs  1  */ 

/*  needs  3  */ 

/*  needs  1  */ 

/*  total  direct  page  use 


static  word  AppID; 
void 

StartupTools () 
{ 

static  struct  { 

word  NumberOf Tools; 

word  Table [5*2] ; 
}  ToolTable  =  { 

5, 

1,  0x0101, 

2,  0x0101, 
8,  miSTVer, 
25,  miNSVer, 
miToolNum,  0x0000 

}; 

MiDriverlnfo  Driverlnfo; 
MiBuflnfo  InBuf Info, OutBuf Info; 


/*  Apps  Memory  Manager  ID  */ 


/*  number  of  tools  in  list  */ 

/*  Tool  Locator  */ 

/*  Memory  Manager  */ 

/*  Sound  Tools  */ 

/*  Note  Synthesizer  */ 

/*  Midi  Tool  Set  */ 

/*  device  driver  info  */ 

/*  I/O  buffer  information  */ 
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handle  ZeroPageHandle; 
ptr  ZeroPagePtr; 

TLStartUpO;  /*  Tool  Locator  startup  */ 

AppID  =  MMStartUpO;  /*  Memory  Manager  startup  */ 

/*  allocate  direct  pages  for  tools  */ 
ZeroPageHandle  =  NewHandle { (long)  TotalDP, 

(word)  AppID, 

(word)   attrBank  |   attrPage  I  attrFixed 

I  attrLocked, 
(long)  0); 
ZeroPagePtr  =  *ZeroPageHandle; 

EMStartUp ( (word) (ZeroPagePtr  +  DPForEventMgr) ,    (word)  0, 
(word)  0, 
(word)  640, 
(word)  0, 
(word)  200, 
(word)   AppID  ) ; 

LoadTools (SToolTable) ;  /*  load  RAM-based  tools  */ 

SoundStartUp ( (word) (ZeroPagePtr  +  DPForSound) ) ; 
NSStartUp(0,   OL) ; 

MidiStartUp (AppID,    (word) (ZeroPagePtr  +  DPForMidi) ) ; 

/*  load  device  driver  */ 
Driverinf o. slot  =2;  /*  use  the  modem  port  */ 

Driverlnfo. external  =0;  /*  internal  slot  */ 

strcpy(DriverInfo.file,   "\p*/system/ drivers/apple .midi" ) ; 
MidiDevice (miLoadDrvr,   &DriverInf o) ; 
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I*  allocate  input  and  output  buffers  */ 

InBuf Info. buf Size  =  0;  /*  default  size  */ 

InBuf Info. address  =0;  /*  MIDI  Tool  Set  will 

allocate  the  buffer  and 
set  its  actual  address  */ 

MidiControl (miSetlnBuf ,   &InBuf Inf o) ; 

OutBuf Info.bufSize  =  0;  /*  default  size  */ 

OutBuf Inf ©.address  =0;  /*  MIDI  Tool  Set  will 

allocate  the  buffer  and 
set  its  actual  address  */ 

MidiControl (miSetOutBuf ,   SOutBuf Inf o) ; 
)  /*  end  of  StartupTools ()  */ 


Reading  time-stamped  MIDI  data 

This  example  shows  a  simple  method  of  recording  time-stamped  MIDI  data  as  it  is 
received.  The  example  records  incoming  data  until  any  key  is  depressed  or  until  the  MIDI 
Tool  Set's  internal  data  buffer  is  full,  whichever  comes  first.  The  routine's  data  buffer 
should  not  be  confused  with  the  MIDI  Tool  Sef s  input  buffer,  which  you  allocate  for  MIDI 
data  by  using  the  MidiControl  call. 
/* 

*  RecordMIDI ( ) 
* 

*  Record  incoming  MIDI  data  with  time  stamps  into  the 

*  global  buffer  "AppMIDIBuf fer"  until  the  buffer  is 

*  full  or  the  user  presses  the  mouse  button. 
*/ 

fdefine  BufSize  (20  *  1024) 

char  SeqBuf fer [BufSize] ; 
int  Buf Index  =  0; 
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void 

RecordMIDI () 
{ 

int  PacketSize; 


/*  size  of  packet  read  */ 


MidiControl (miFlushlnput,   OL)  ; 

MidiClock (miSetFreq, OL) ; 

MidiClock (ndSetClock,   OL) ; 
MidiClock (miStartClock,   OL) ; 
MidiControl (miSetlnMode, 

(long)miPacketMode) ; 
MidiControl (miStartlnput,   OL) ; 


/*  discard  contents 
of  input  buffer  */ 

/*  set  clock  to 

default  frequency  */ 

/*  clear  the  clock  */ 

/*  start  the  clock  */ 

/*  set  MIDI  input  mode  */ 
/*  start  MIDI  input  */ 


Buf Index  =  0; 


while   (  Button (0)  ==  0  )  /*  until  presses  mouse  */ 

{ 

PacketSize  =  MidiReadPacket (SeqBuffer+Buf Index, 

Buf Size-Buf Index) ; 

if    (  toolErr) 


{ 


} 

else 
{ 

} 


if   (_toolErr  ==  miArrayErr) 


break; 


/*  our  buffer  is  full  */ 


) 

else 
{ 

} 


printf("MIDI  error  $%4 . 4X\n",_toolErr) ; 


Buflndex  +=  PacketSize; 
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/*  stop  recording  */ 
MidiControl (mistoplnput,    OL)  ; 
MidiClock (miStopClock,    OL) ; 


/*  stop  MIDI  input  */ 
/*  stop  the  clock  */ 


/*  show  user  recording  statistics  */ 


printf ("Bytes  recorded:  %d\n", Buf Index) ; 
printf ("Maximum  bytes  buffered:  %ld\n", 


Midilnfo (miMaxInChars) ) ; 
/*  end  of  RecordMIDIO  */ 


This  example  is  a  simple  subroutine  that  continuously  plays  previously  recorded  time-stamped  MIDI 
data  until  the  user  presses  any  key. 

/* 

*  PlayMIDK) 


*  This  routine  repeatedly  plays  the  MIDI  data  that  was 

*  previously  recorded  and  stored  into  the  global  buffer 

*  "SeqBuffer"  until  the  user  presses  the  mouse  button. 
*/ 

void 

PlayMIDI 0 
{ 

long  FirstTime; 
int  Playlndex; 

if   (Buf Index  ==  0) 


printf ("You  must  record  or  load  MIDI  data  first\n"); 
return; 


/*  find  the  first  time  stamp  in  the  sequence  and  subtract 
a  little  */ 

FirstTime  =  * ( (long  *)    (SeqBuf fer+2) )  ; 
if   (FirstTime  >  0x200) 

FirstTime  -=  0x200; 

else 

FirstTime  =  0; 


* 
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MidiControl (miFlushOutput, (long) (OxFFFF  «  16)); 

/*  empty  output  buffer  */ 
MidiClock (miSetClock, FirstTime) ;         /*  set  clock  before 

first  time  stamp*/ 
MidiClock (miStartClock, OL) ;  /*  start  clock  */ 

MidiControl (miSetOutMode,    (long) miPacketMode) ; 

/*  set  output  mode  */ 
MidiControl (miStartOutput, OL) ;  /*  start  output  */ 

Playlndex  =  0; 

/*  Repeatedly  play  song  */ 

while   (  Button (0)   ==  0  )  /*  Until  presses  mouse  */ 

( 

Playlndex  +=  MidiWritePacket (SeqBuf f er  +  Playlndex); 

/*  write  next  packet  */ 
if   (Playlndex  ==  Buf Index)         /*  Time  to  repeat?  */ 
{ 

while   (  Button (0)   ==  0  &&  Midilnf o (miOutputChars) ) 

;  /*  wait  for  the  song  to  end  */ 


if   (Button(O)    II  ILoopPlayback) 
break; 

MidiClock (miSetClock, FirstTime) ; 

/*  restart  clock  */ 

Playlndex  =  0; 

} 

} 


MidiControl (miFlushOutput, OxlOL) ; 

/*  flush  output  buffer 

&  turn  all  notes  off  */ 
MidiClock (ndStopClock, OL) ;  /*  stop  the  clock  */ 

MidiControl (miStopOutput, OL) ;  /*  stop  output  */ 

}  /*  end  of  PlayMIDIO  */ 
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Fast  access  to  MIDI  Tool  Set  routines 

Because  of  the  tight  timing  requirements  of  MIDI  processing,  there  are  many  time-critical 
situations  in  which  the  overhead  of  a  tool  call  can  be  problematic.  When  you  need  to  save 
as  much  time  as  possible,  you  may  want  to  call  MIDI  Tool  Set  routines  directly  and  avoid 
the  time  needed  to  make  a  tool  call.  The  following  example  demonstrates  how  to  do  this 
in  65816  assembly  language.  This  example  can  save  approximately  85  microseconds  per 
call.  This  time  saving  can  be  very  helpful  in  an  application  that  makes  numerous  calls  to 
MidiReadPacket  andMidiWritePacket. 


look  up  the  address  of  MidiWritePacket   (as  an  example) 


pushlong  #0 
pushword  #0 
pushword  #$0E20 
_GetFuncPtr 
pla 

sta  MidiWriteAddr 
pla 

sta  MidiWriteAddr+2 


space  for  result 
system  tool 

tool  and  function  number 


save  the  address 
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;  do  this  instead  of  _MidiWritePacket 

f 

jsl  MidiWriteGlue 


IMPORTANT  NOTE:  The  variable  "MidiDP2"  must  contain  the 
address  of  the  second  page  of  bank  zero  memory  allocated  for 
the  MIDI  Tool  Set's  direct  page.  If  MidiStartUp  is  given 
a  starting  address  of  X,  then  MidiDP2  =  X  +  $100. 


MidiWriteGlue      jsl  MidiWriteGluel 
rtl 

MidiWriteGluel  Ida  MidiWriteAddr+1 
pha 
phb 

Ida  MidiWriteAddr 
sta  l,s 
Ida  MidiDP2 


GlueReturn  rtl 
MidiWriteAddr      ds  4 


push  an  extra  RTL 
address 

;  simulate  a  Tool  call 
;  to  MidiWritePacket 


the  A  register  must 
contain  the  address  of 
the  MIDI  Tool 
Set's  direct  page  address 
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MIDI  application  considerations 

This  section  contains  advice  on  a  number  of  topics,  and  is  intended  to  help  you  create 
more  satisfying  MIDI  applications, 

MIDI  and  AppleTalk 

The  MIDI  Tool  Set  is  not  designed  to  operate  with  AppleTalk®  enabled.  The  Apple  IIGS  is 
not  fast  enough  to  process  both  AppleTalk  interrupts  and  MIDI  interrupts  simultaneously. 
If  an  application  that  uses  the  MIDI  Tool  Set  runs  with  AppleTalk  enabled,  you  should 
expect  occasional  MIDI  input  errors  and  output  delays.  For  most  programs,  even  one 
MIDI  error  is  difficult  to  handle,  so  you  should  probably  recommend  that  applications 
that  use  the  MIDI  Tool  Set  not  be  used  with  AppleTalk  enabled. 

Disabling  interrupts 

Several  tool  calls  that  disable  interrupts  can  cause  loss  of  MIDI  data.  These  include  calls 
that  access  the  disk  drives,  Event  Manager  calls,  and  Dialog  Manager  calls. 

The  rate  of  MIDI  data  transfer  leaves  little  margin  for  error  in  the  MIDI  Tool  Set's 
operation.  The  rate  at  which  the  tool  set  must  retrieve  MIDI  data  places  great  demands  on 
the  system's  computational  resources.  If  possible,  an  application  should  avoid  disabling 
interrupts  while  reading  MIDI  data.  If  a  program  must  disable  interrupts  while  reading 
MIDI  data,  it  should  not  do  so  for  longer  than  270  microseconds. 

In  cases  where  compliance  with  these  restrictions  is  impossible,  you  can  use  the 
MidiinputPoii  vector.  This  vector  is  provided  for  those  applications  that  must 
disable  interrupts  for  dangerously  long  periods.  To  call  MidiinputPoii,  execute  a  jsl 
to  $E101B2.  If  the  MIDI  Tool  Set  has  not  been  started  up,  or  if  the  MIDI  input  process  has 
not  been  started,  the  vector  will  return  immediately.  Any  MIDI  data  that  were  present  on 
the  call  to  the  vector  will  appear  in  the  input  buffer  that  you  allocated  with 

MidiControl. 

♦  Note:  If  you  need  the  values  of  the  A,  X,  and  Y  registers,  you  must  save  them  yourself 
before  calling  the  vector.  The  direct-page  and  data  bank  registers  are  preserved. 
MidiinputPoii  must  be  called  only  in  full  native  nx)de. 
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▲  Warning       Do  not  call  MidiinputPoii  before  loading  the  MIDI  Tool  Set  in  a 
system  with  a  Sound  Tool  Set  version  eariier  than  2.3  or  system 
software  earlier  than  4.0.  Doing  so  will  cause  a  system  failure.  ▲ 

If  you  use  the  MidiinputPoii  vector,  you  must  ensure  that  it  is  called  at  least  every  270 
microseconds,  or  MIDI  data  may  be  lost.  A  call  to  the  vector  when  no  data  are  present 
returns  in  from  8  to  30  microseconds,  and  when  data  are  present  the  veaor  can  take  up  to 
450  microseconds,  at  150  microseconds  per  character  read. 

You  can  call  MidiReadPacket  and  MidiwritePacket  inside  internipt-service 
routines,  because  they  perform  polling  automatically.  Other  tool  sets  do  not  perform 
MIDI  polling,  so  MIDI  applications  should  not  make  calls  to  other  tool  sets  in  interrupt- 
service  routines. 

A  Warning       Do  not  make  MIDI  Tool  Set  calls  other  than  MidiReadPacket  and 
MidiwritePacket  from  intermpt-service  routines.  Doing  so  can 
cause  unpredictable  system  failure.  ▲ 

Whenever  possible,  you  should  use  MIDI  interface  cards  that  support  MIDI  data 
buffering.  By  storing  some  received  data,  these  cards  relieve  the  time  constraints  on  your 
application. 

MIDI  and  other  sound-related  tool  sets 

If  you  use  the  recommended  versions  of  the  Note  Synthesizer,  Note  Sequencer,  and 
Sound  Tool  Set  (see  Chapter  51,  "Tool  Locator  Update,"  for  details),  these  tool  sets  are 
fully  compatible  with  the  MIDI  Tool  Set  and  do  not  cause  MIDI  data  losses.  It  is  possible 
to  write  programs  that  use  the  Note  Sequencer  to  play  notes  on  the  internal  voices  of  the 
Apple  IIGS  and  on  an  external  MIDI  synthesizer  while  simultaneously  accepting  MIDI  input 
from  an  external  keyboard  and  translating  it  to  Note  Synthesizer  commands  to  play  the 
notes. 

The  MIDI  clock 

This  section  discusses  the  technique  currently  used  to  generate  MIDI  time-stamps.  Note 
that  this  technique  may  not  be  used  on  future  Apple  IIGS  machines.  Any  application  that 
employs  a  similar  technique  to  implement  timing  may  be  incompatible  with  future 
systems. 
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Properly  time-stamping  MIDI  input  data  requires  a  clock  with  resolution  better  than  one 
millisecond.  When  a  long  stream  of  MIDI  data  is  received  in  a  short  time  period  (such  as 
when  the  user  plays  a  large  chord  on  a  MIDI  keyboard),  each  note  must  be  accurately  time- 
stamped.  However,  the  Apple  IIGS  cannot  process  interrupts  quickly  enough  to  satisfy 
this  requirement. 

To  provide  a  reasonable  clock  resolution,  the  Apple  IIGS  MIDI  time-stamp  is 
implemented  using  one  of  the  system's  DOC  generators.  The  MIDI  tool  set  loads  the  DOC 
with  a  256-byte  waveform  consisting  of  consecutive  values  from  $01  to  $FF  (followed  by 
an  additional  byte  of  $FF),  and  sets  the  DOC  to  play  this  waveform  at  zero  volume,  When 
a  MIDI  character  is  received,  the  time-stamping  routine  uses  the  value  from  this  DOC  for 
the  low-order  byte  of  the  time-stamp.  The  system  obtains  the  high-order  3  bytes  from  a 
counter  that  is  incremented  each  time  the  DOC  cycles  through  its  waveform  (once  every 
19.45  milliseconds  at  the  default  clock  rate).  This  technique  reduces  the  system  interrupt 
load  to  a  manageable  level  while  also  providing  sufficiently  fine  clock  resolution  to 
correcdy  process  MIDI  data. 

Because  the  MIDI  clock  is  actually  a  DOC  generator,  you  cannot  use  that  generator  while 
the  clock  is  running;  under  these  circumstances,  only  13  generators  are  available  for  general 
use.  The  clock  also  uses  the  first  256  bytes  of  DOC  RAM  for  its  waveform,  so  mnning  the 
clock  reduces  the  memory  available  for  application  waveforms.  While  the  clock  is  running 
you  must  not  use  the  Sound  Tool  Set's  free-form  synthesizer  (the  FFStartsound  call). 
The  frequency  and  duration  of  Sound  Tool  Set  interrupts  also  interferes  with  the  MIDI 
Tool  Set's  abUity  to  perform  its  services  often  enough  to  prevent  data  loss. 

Input  and  output  buffer  sizing 

You  should  adjust  the  MIDI  input  buffer  size  for  the  amount  of  data  you  can  expect  to 
receive  before  the  application  processes  it.  Any  process  that  competes  with  the 
application  for  processor  time,  such  as  Note  Synthesizer  calls  to  play  complex  envelopes, 
reduces  the  frequency  at  which  the  application  can  call  MidiReadPacket  and  process 
the  data  in  the  input  buffer.  If  the  input  buffer  fills  before  it  can  be  processed,  data  will 
be  lost.  Complex  applications  that  use  time-consuming  tool  calls  therefore  require  large 
input  buffers. 

You  can  estimate  the  size  of  the  needed  input  buffer  from  the  size  of  the  largest  MIDI 
System  Exclusive  command  you  intend  to  receive.  The  default  size  of  the  input  and 
output  buffers  is  8  KB.  This  is  the  size  of  two  very  large  System  Exclusive  packets.  You 
should  choose  a  size  that  is  large  enough  to  accommodate  two  of  the  largest  System 
Exclusive  packets  you  expect  to  receive  so  that  the  MIDI  tools  can  receive  one  packet 
and  still  have  room  for  anodier.  In  packet  mode,  the  MIDI  Tool  Set  does  not  return  a 
packet  until  it  has  received  all  of  it,  and  MIDI  data  may  continue  to  arrive  while  the  tool 
set  is  returning  the  first  packet. 
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The  maximum  buffer  size  is  32K,  so  your  application  may  liave  to  run  the  MIDI  interface  in 
raw  mode  (rather  than  packet  mode)  in  order  to  support  System  Exclusive  messages 
longer  than  16KB. 

You  might  want  to  keep  statistics  on  the  maximium  number  of  data  bytes  in  the  input 
buffer  in  order  to  allow  your  application  toadjust  the  input  buffer  size  intelligently. 
Several  MIDI  Tool  Set  calls  return  information  you  can  use  for  this  purpose;  see  "MIDI 
Tool  Calls"  in  this  chapter  for  more  detailed  information  on  data  returned  by  MIDI  tool 
calls  (especially  the  miMaxInChars  and  miMaxOutChars  functions  of  the  Midiinf  o 

call). 

Loss  of  MIDI  data 

The  Apple  6850  driver  was  designed  to  work  with  non-buffered  interface  cards.  When  you 
use  this  driver  and  the  desktop  interface  you  may  lose  MIDI  data.  To  avoid  this  data  loss, 
you  can 

■  Use  a  different,  buffered  6850-based  MIDI  card  along  with  a  driver  that  supports  the 
card 

■  Prevent  the  user  from  moving  the  cursor  or  making  menu  selections  when  your  program 
is  recording  MIDI  data 

Number  of  MIDI  interfaces 

Note  that  the  Apple  IlGS  can  support  only  a  single  MIDI  interface  at  a  time.  If  you  try  to 
support  more  than  one  MIDI  interface  at  the  same  time,  you  will  lose  MIDI  data. 


Chapter  38  MIDI  Tool  Set  38-25 


Apple  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


MIDI  Housekeeping  calls 

The  following  MIDI  calls  perform  common  tool  set  functions. 
MidiBootlnit  $0120 

Initializes  the  MIDI  Tool  Set;  called  only  by  the  Tool  Locator. 

▲  Warning     An  application  must  never  make  this  call.A 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  None 

C  extern  pascal  void  MidiBootlnit () ; 
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MidiStartUp  $0220 

Starts  up  the  MIDI  tools  for  use  by  an  application,  Applications  should  make  this  call 
before  any  other  calls  to  the  MIDI  tools.  Normally  an  application  must  next  call 
MidiDevice  to  load  a  MIDI  device  driver,  and  then  mid i control  to  allocate  any 
necessary  input  or  output  buffers. 

Parameters 

Stack  before  call 

Previous  contents 


dPageAddr 


userlD 


Word— Application  user  ID  (for  the  Memory  Manager) 
Word— Beginning  of  MIDI  direct-page  space 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


$0812 


noSAppInitErr 


The  Sound  Tool  Set  has  not  been 
started  up. 


C 


extern  pascal  void  MidiStartUp (userlD,  dPageAddr); 


Word 


userlD,  dPageAddr; 


dPageAddr 


Must  specify  3  pages  of  page-aligned  direct-page  space  for  the  MIDI 
tools. 
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MidiShutDown  $0320 

Shuts  down  the  MIDI  Tool  Set.  An  application  that  uses  the  MIDI  tools  should  make  this 
call  before  it  quits.  MidiShutDown  deallocates  the  input  and  output  buffers,  stops  the 
MIDI  clock  and  deallocates  its  generator,  and  shuts  down  the  hardware  interface.  The 
call's  actions  take  place  immediately,  so  the  application  should  take  any  necessary  steps 
to  see  that  all  recent  MIDI  output  has  been  sent  before  shutting  down  the  tools  (see  the 
MidiControl  call). 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  None 

C  extern  pascal  void  MidiShutDown () ; 
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MidiVersion  $0420 

Returns  the  version  number  of  the  currently  loaded  MIDI  tools.  For  information  on  the 
format  of  the  returned  versionNum,  see  Appendix  A,  "Writing  Your  Own  Tool  Set,"  in 
Volume  2  of  the  Toolbox  Reference. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


versionNum 


Word— MIDI  tools  version  number 


<— SP 


Errors 


None 


C 


extern  pascal  Word  MidiVersion () ; 
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MidiReset  $0520 

Resets  the  MIDI  tools;  called  by  system  reset, 

This  tool  call  causes  the  MIDI  device  driver  reset  routine  to  be  invoked,  in  order  to  allow 
for  reset-specific  processing  that  may  differ  from  shutdown  processing. 

A  Warning     An  application  must  never  make  this  call.A 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  None 

C  extern  pascal  void  MidiReset () ; 
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MidiStatus  $0620 

Returns  a  Boolean  value  of  TRUE  if  the  MIDI  tools  are  active  and  FALSE  if  they  are  not. 

♦  Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  MidiStatus,  your  program  need  only  check  the 
value  of  the  returned  flag.  If  the  MIDI  Tool  Set  is  not  active,  the  returned  value  will  be 
FALSE  (NIL). 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


activeFlag 


Word— Boolean;  TRUE  if  the  tool  set  is  active 


<— SP 


Errors 


None 


C 


extern  pascal  Word  MidiStatus () ; 
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MIDI  tool  calls 

All  the  MIDI  Tool  Set  calls  are  new  calls,  added  to  the  toolbox  since  publication  of  the 
first  two  volumes  of  the  Apple  IIGS  Toolbox  Reference. 

The  routines  used  to  work  with  the  MIDI  Tool  Set  are  Midicontroi,  Midioevice, 
MidiClock,  Midiinf  o,  MidiReadPacket,  and  MidiWritePacket.  Four  of  these 
calls  are  multifunction  calls,  which  perform  different  actions  depending  on  a  control 
parameter  passed  to  them.  The  workhorse  of  the  group  is  Midicontroi,  which  performs 
18  different  functions,  depending  on  the  control  function  paranieter.  The  other 
multipurpose  calls  are  Midioevice,  MidiClock,  and  Midiinf  o. 
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MidiClock  $0B20 


Controls  operation  of  the  optional  time-stamp  clock.  The  clock  ticks  once  every  76 
microseconds  with  default  settings,  and  allows  MIDI  data  to  be  input  and  output  with 
precise  timing.  The  funcNum  parameter  specifies  which  clock  function  to  perform,  and 
the  arg  parameter  provides  the  argument  to  the  selected  function. 

Parameters 

Stack  before  call 


Previous  contents 


funcNum 


arg 


Word— Specifies  Midi  clock  function  number 
Long— Argument  passed  to  Midiciock  function 

<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 


<— SP 

See  the  Midiciock  function  descriptions  below, 
extern  pascal  void  Midiciock (funcNum,  arg) ; 


Word  funcNum; 
Long  arg; 

funcNum  Specifies  the  Midiciock  function  to  be  performed.  Four  different 

functions  are  provided  for  clock  control.  They  are 

0     misetciock      The  value  of  «^  becomes  the  new  value  of  the  time-Stamp  clock. 

The  most  significant  bit  of  the  arg  parameter  must  be  set  to  0.  There  is  a 
limit  to  the  precision  with  which  the  clock  can  be  set.  The  least 
significant  byte  of  the  time-stamp  clock  will  always  be  0  if  the  clock  is 
stopped.  If  the  clock  is  running,  the  value  of  the  least  significant  byte 
will  be  undefined  for  the  purposes  of  this  call.  The  result  is  that  an 
application  can  set  the  clock  only  to  within  20  milliseconds  of  a 
particular  value  with  the  clock  frequency  at  its  default  value. 

Errors  None 
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1  miStartClock 

Allocates  a  DOC  generator,  writes  consecutive  values  from  $01  through 
$FF  into  the  first  page  of  the  DOC  RAM,  and  starts  the  clock.  By  default, 
the  clock  starts  counting  at  0.  If  the  application  stops  the  clock  and 
restarts  it,  the  clock  starts  with  the  same  value  it  had  when  it  stopped, 
unless  the  value  is  changed  with  an  misetciock  call.  Note  that  only  the 
high-order  3  bytes  are  preserved;  the  low-order  byte  always  starts  at  $01. 
You  should  call  mistartciock  before  mistartinput  if  you  are  using 
time-stamps. 

Start  the  MIDI  clock  before  starting  to  receive  or  transmit  MIDI  data. 
The  process  of  starting  the  clock  is  time-consuming  and  disables 
interrupts,  so  it  could  cause  MIDI  data  to  be  lost  if  it  is  done  while  the 
application  is  receiving  a  MIDI  transmission.  The  Sound  Tool  Set  and  the 
Note  Synthesizer  must  be  loaded  and  started  up  before  this  call  is  issued. 

Errors 

$0810  noDOCFndErr  No  DOC  or  DOC  RAM  was  found. 

$1921  nsNotAvaii    No  DOC  generator  was  available. 

$1923  nsNotinit     The  Note  Synthesizer  was  not  started. 

2  miStopClock 

Stops  the  MIDI  time-stamp  clock  and  releases  the  DOC  generator  and  its 
associated  RAM  for  use  by  the  Note  Synthesizer.  The  MIDI  tools 
time-stamp  MIDI  data  received  while  the  clock  is  stopped  with  the  value 
of  the  stopped  clock  in  the  high-order  3  bytes,  and  the  low-order  byte 
set  to  $00.  The  MIDI  tools  will  not  send  any  output  packets  with 
time-stamps  greater  than  the  value  of  the  stopped  clock  until  the  clock  is 
restarted  or  reset. 

Errors  None 
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3     misetFreq  Sets  the  frequency  for  the  MIDI  time-stamp  clock.  The  arg  parameter 
contains  the  number  of  clock  ticks  to  be  processed  per  second.  Valid 
values  lie  in  the  range  from  1  to  65,535;  a  0  value  specifies  the  default 
setting  (13,160  ticks  per  second). 

Since  the  clock  frequency  affects  the  rate  of  playback,  be  careful  to  set 
the  clock  frequency  at  playback  to  the  same  value  that  was  used  when 
the  sequence  was  recorded,  unless  you  intend  to  vary  the  tempo. 

See  the  Midi  Info  call  for  information  about  how  to  read  the  current 
clock  frequency  and  value. 

Errors 

$2009       miBadFreqErr  Unable  to  set  MIDI  clock  to  the  specified 

frequency  (use  the  Midiinf  o  tool  call  to 
get  the  current  value). 


Chapter  38  MIDI  Tool  Set  38-35 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


MidiControl  $0920 

Performs  18  different  control  functions  required  by  the  MIDI  Tool  Set. 

Tlie  funcNum  parameter  selects  which  function  is  to  be  performed,  and  the  arg  parameter 
passes  any  argument  required  by  that  function. 

Parameters 

Stack  before  call 


Previous  contents 


funcNum 


arg 


Word— Specifies  MidiControi  function  number 
Long— Argument  passed  to  Midi  control  function 

<— SP 


Stack  after  call 


Prmoiis  contents 


Errors 
C 


funcNum 


<— SP 

See  the  Midicontroi  function  descriptions. 

extern  pascal  void  MidiControl (funcNum,  arg) ; 

Word  funcNum; 
Long  arg; 

Specifies  the  MidiControl  function  to  be  performed: 


miSetRTVec 


Sets  the  real-time  vector.  The  arg  parameter  contains  the  address  of  a 
service  routine  in  the  application.  When  the  MIDI  Tool  Set  receives  MIDI 
real-time  commands,  it  calls  this  service  routine.  A  value  of  0  in  this 
parameter  disables  the  service  routine.  See  "MIDI  Tool  Set  service 
routines"  earlier  in  this  chapter  for  more  information  on  the  real-time 
command  routine. 


Errors 


None 


38-36    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


1  miSetErrVec 

Sets  the  real-time  error  vector.  The  arg  parameter  contains  the  address 

of  a  service  routine  in  the  application.  The  MIDI  Tool  Set  calls  this 
routine  in  the  event  of  a  MIDI  real-time  error.  A  value  of  0  in  the 
parameter  disables  the  service  routine.  See  "MIDI  Tool  Set  service 
routines"  earlier  in  this  chapter  for  more  information  on  the  real-time 
error  routine. 

Errors  None 

2  itiiSetlnBuf 

Sets  the  MIDI  input  buffer.  The  arg  parameter  contains  a  pointer  to  a  6- 
byte  record.  The  fields  of  this  record  are 


Word— Size  of  input  buffer  (in  bytes) 


Long— Pointer  to  buffer 


$00 

buf size 

$02 

bufPtr 

If  the  bufPtr  parameter  is  set  to  0,  the  MIDI  Tool  Set  will  allocate  the 
input  buffer.  If  the  buf  size  parameter  is  set  to  0,  the  MIDI  tools  will 
allocate  a  buffer  8  KB  in  size.  Note  that  these  parameters  are 
independent;  your  program  may  set  either  one  of  them  to  0.  If  the 
application  allocates  the  buffer,  it  must  be  nonpurgeable,  in  a  fixed 
location,  and  must  not  cross  bank  boundaries.  The  size  must  be  greater 
than  or  equal  to  32  bytes  and  less  than  or  equal  to  32  KB. 

Errors 

$2002         iniArrayErr   Array  was  an  invalid  size. 
Memory  Manager  errors  Returned  unchanged. 
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3  miSetOutBuf 

Sets  the  MIDI  output  buffer.  The  arg  parameter  contains  a  pointer  to  a  6- 

byte  record.  The  fields  of  this  record  are 


$00 

—  bufSlze 

Word— Size  of  output  buffer  (in  bytes) 

$02 

-  bufPtr 

Long— Pointer  to  buffer 

If  the  bufPtr  parameter  is  set  to  0,  the  MIDI  Tool  Set  will  allocate  the 
output  buffer.  If  the  buf  size  parameter  is  set  to  0,  the  MIDI  Tool  Set 
will  allocate  a  buffer  8  KB  in  size.  Note  that  these  parameters  are 
independent;  your  program  may  set  either  one  of  them  to  0.  If  the 
application  allocates  the  buffer,  it  must  be  nonpurgeable,  in  a  fixed 
location,  and  must  not  cross  bank  boundaries.  The  size  must  be  greater 
than  or  equal  to  32  bytes  and  less  than  or  equal  to  32KB. 

Errors 

$2002         loiArrayErr   Array  was  an  invalid  size. 
Memory  Manager  errors        Returned  unchanged 

4  miStartlnput 

Starts  an  interrupt-driven  process  that  reads  MIDI  data  into  the  MIDI 
Tool  Set's  input  buffer.  Any  data  being  received  when  this  call  is  made  are 
discarded  until  the  first  MIDI  status  byte  is  received.  An  application  can 
retrieve  these  data  with  a  MidiReadPacket  call.  The  arg  parameter 
contains  the  address  of  a  service  routine  to  be  called  when  the  first 
packet  is  available  in  a  previously  empty  input  buffer.  The  system  will  call 
the  service  routine  immediately  if  a  complete  MIDI  packet  is  available  in 
the  input  buffer  when  this  function  is  called.  A  value  of  0  disables  this 
service  routine. 

Errors 

$2007         iniNoBufErr   No  buffer  allocated. 
$200C         miNoDevErr   No  device  driver  loaded. 
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5  miStartOutput 

Starts  an  interrupt-driven  process  that  writes  application  MIDI  data  to 
the  MIDI  Tool  Set's  output  buffer.  Your  application  uses 
MidiwritePacketcalls  to  queue  data  to  this  process.  The  arg 
parameter  contains  the  address  of  a  service  routine  called  when  the 
output  buffer  becomes  completely  empty.  A  value  of  0  disables  this 
service  routine. 

Errors 

$2007         miNoBuf  Err   No  buffer  allocated. 
$200C         miNoDevErr   No  devicc  driver  loaded. 

6  miStopInput 

Causes  the  MIDI  Tool  Set  to  ignore  MIDI  data  until  the  next 
miStartlnput  call. 

Errors  None 


7  miStopOutput 

Halts  MIDI  output  until  the  next  mistaftoutput  call. 

Errors  None 


miFlushlnput 

Discards  the  contents  of  the  current  input  buffer. 

Errors 


$2007         miNoBufErr   No  buffer  allocated. 


miFlushOutput 

Discards  the  contents  of  the  current  output  buffer.  The  arg  parameter 
selects  the  method: 

arg  value  Action 

$0000  OOXX        Wait  for  the  current  packet  to  finish  transmission,  then 
turn  off  all  notes  that  have  not  been  turned  off  in  channel 
XX.  If  XX  =  $10,  turn  off  notes  in  all  channels. 

$0001  OOXX        Wait  for  current  packet  to  finish  transmission,  then  turn 

off  all  possible  notes  (pitch  $00  through  $7F)  in  channel  XX. 
If  XX  •=  $10,  turn  off  notes  in  all  channels.  Note  that  this 
option  may  take  several  seconds  to  complete. 

$FFFFXXXX       Discard  the  contents  of  the  output  buffer  immediately 
without  turning  off  any  notes. 
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Some  synthesizers  may  require  a  short  delay  between  the  high-speed 
NoteOff  commands  generated  by  this  function,  In  such  cases,  use  the 
misetDeiay  function  of  this  tool  call  to  control  that  delay.  The 
NoteOff  side-effect  can  be  useful  for  shutting  off  notes. 

Errors 

$2005         mioutof  f  Err  MDI  output  disabled. 
$2007         miNoBuf  Err   No  buffer  allocated. 

10  miFlushPacket 

If  there  is  a  complete  packet  in  the  input  buffer,  this  call  discards  that 
packet.  If  there  is  no  complete  packet  available,  this  call  does  nothing. 
This  call  is  especially  useful  for  discarding  large  System  Exclusive  packets 
that  are  of  no  interest  to  your  application. 

Errors 


$2007         miNoBuf  Err   No  buffer  allocated. 


11  miWaitOutput 

Ceases  execution  until  the  output  buffer  becomes  empty.  This  function 

may  never  retum  if  output  is  disabled. 
Errors 


$2007         miNoBufErr    No  buffer  allocated. 


12  nuLSetlnMode 

Set  input  mode.  The  arg  parameter  selects  the  input  mode. 

arg  value         Input  mode 

0  Raw  mode.  MIDI  data  is  converted  to  packets,  with 
length-of-packet  and  time-stamp  bytes  added  to  the  front 
of  each  packet. 

1  Packet  mode.  Packet  mode  is  the  default  mode.  MIDI 
data  is  converted  to  packets,  with  length-of-packet  and 
time-stamp  bytes  added  to  the  front  of  each  packet. 
Running  status  bytes,  which  MIDI  may  discard  to 
abbreviate  transmitted  data,  are  restored. 

The  input  buffer  is  cleared  when  this  call  is  made  because  the  input  buffer 
cannot  contain  data  in  more  than  one  format  at  a  time. 


Errors  None 
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13  miSetOutMode 

The  arg  parameter  selects  the  output  mode. 
arg  value         Input  mode 

0  Raw  mode.  This  mode  is  very  similar  to  packet  mode,  but 
no  attempt  is  made  to  keep  track  of  which  notes  are  on. 
Running  status  optimization  is  still  performed  unless 
explicitly  disabled  by  mioutputstat.  Because  no  record 
is  kept  of  which  notes  are  on,  all  notes  that  are  turned  on 
must  be  explicitly  turned  off. 

1  Packet  mode.  Packet  mode  is  the  default  mode.  Your 
application  must  format  output  data  into  valid  MIDI 
packets  (see  "MIDI  packet  format"  in  this  chapter  for 
details).  The  MIDI  tools  track  NoteOn  and  NoteOff 
commands. 

Your  program  should  wait  for  a  clear  output  buffer  before  switching 
modes.  If  the  output  buffer  contains  mbced-mode  data,  the  MIDI  tools 
may  not  track  NoteOn  and  NoteOff  commands  correcdy. 

Errors  None 

14  miClrNotePad 

Erases  the  MIDI  Tool  Set's  record  of  which  notes  are  on  and  which  are 
off.  This  call  causes  die  tool  set's  record  to  show  that  all  notes  are  off. 

Errors  None 

15  iniSetDelay 

Sets  a  delay  value  for  use  with  MIDI  synthesizers  diat  cannot  process 
MIDI  data  at  the  full  MIDI  transfer  rate.  The  low  word  of  arg  specifies  a 
minimum  delay  between  packet  sends  in  units  of  76  microseconds.  The 
delay  mechanism  is  most  effective  when  the  MIDI  Tool  Set  clock  is 
running,  because  it  can  use  the  clock  to  time  the  delay.  If  the  clock  is  not 
running,  the  tool  set  must  use  code  loops  to  create  the  delay,  which  is 
inherently  less  accurate,  and  which  uses  more  processor  time.  The  default 
delay  value  is  0,  or  no  delay. 

Many  synthesizers  may  need  a  delay  value  in  order  to  correcdy  process 
the  many  high-speed  NoteOff  commands  generated  by  die 
miFiushoutput  funcUon. 

Errors  None 
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16  miOutputStat 

Enables  or  disables  transmission  of  standard  MIDI  running  status.  When 
running  status  is  enabled,  MIDI  status  bytes  are  sent  only  when  they 
change  or  are  otherwise  absolutely  necessary.  This  optimization  speeds 
transmission  and  reduces  CPU  overhead,  but  can  cause  malfunctions  if 
the  synthesizer  and  computer  disagree  on  the  current  value  of  the  status 
byte. 

The  low  word  of  arg  contains  the  enable/disable  flag 

$0000      Disable  running  status 
$0001      Enable  running  status 

Whatever  the  value  of  the  parameter,  the  next  MIDI  packet  after  this  call 
contains  a  status  byte,  so  it  can  be  useful  to  make  this  call  periodically  to 
ensure  that  the  Apple  IIGS  and  the  external  device  agree  about  the  current 
value  of  the  status  byte. 

Errors  None 

17  lailgnoreSysEx 

Specifies  whether  to  ignore  MIDI  System  Exclusive  data.  System 
Exclusive  packets  begin  with  the  value  $F0.  If  the  application  configures 
the  MIDI  Tool  Set  to  ignore  System  Exclusive  packets,  the  system  will 
not  buffer  them,  and  the  application  will  not  receive  them.  The  arg 
parameter  contains  a  flag  indicating  how  to  process  System  Exclusive 
data: 

$0000      Ignore  System  Exclusive  data 

$0001      Accept  System  Exclusive  data  (default) 

Errors  None 
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MidiDevice  $0A20 

Allows  an  application  to  select,  load,  and  unload  device  drivers  for  use  with  the  tools. 
MidiDevice  loads  and  unloads  MIDI  device  drivers,  which  allow  the  MIDI  tools  to  drive 
a  particular  MIDI  interface.  The  present  version  of  the  MIDI  Tool  Set  supports  the  Apple 
MIDI  Interface  and  ACIA  6850  MIDI  Interface  cards. 

The  call  interprets  the  driverlnfo  parameter  as  the  address  of  the  driver  to  be  loaded.  The 
funcNum  parameter  specifies  whether  the  driver  is  to  be  loaded  or  unloaded. 

Parameters 

Stack  before  call 


Previous  contents 


funcNum 


drvrPtr 


Word— Specifies  MidiDevice  function  number 
Long— Pointer  to  device  driver  information 

<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 


funcNum 
0 


<— SP 

See  the  MidiDevice  function  descriptions. 

extern  pascal  void  MidiDevice (funcNum,  drvrPtr) ; 

Word  funcNum; 
Pointer  arg; 

Specifies  the  MidiDevice  function  to  be  performed 
Not  yet  implemented 
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miLoadDrvr 

Loads  the  specified  device  driver  into  memory,  after  shutting  down  and 
unloading  any  previously  loaded  device  drivers.  It  then  initializes  the 
newly  loaded  driver.  The  drvrPtr  parameter  points  to  a  device  driver 
record,  which  specifies  a  device  driver  to  be  loaded. 

Errors 

$2008         miDriverErr      Specified  device  driver  invalid. 
$2080         miDevNotAvaii    MIDI  interface  not  available. 
$2081         itiiDevsiotBusy    Specified  slot  not  selected  in  Control 

Panel. 

$2082         nd-DevBusy         MIDI  interface  already  in  use. 
$2084         itiiDevNoConnect  No  connection  to  MIDI  interface. 
$2086         miDevVersion     ROM  version  or  machine  type 

incompatible  with  device  driver. 
$2087         miDevintHndir   Conflicting  interrupt  handler  installed. 


2  miUnloadDrvr 

Shuts  down  and  unloads  the  currently  loaded  device  driver.  Terminates 
MIDI  transmission  or  reception  if  they  are  currendy  active.  Releases 
memory  occupied  by  the  device  driver. 

Errors  None 

drvrPtr  The  record  pointed  to  by  the  drvrPtr  parameter  contains  device 

driver  information: 


$00 
$02 
$04 


slotNumber 


slotFXag         —  Word 


Word 


driverpath        :  Pascal  String 


SlotNumber  Specifies  the  system  slot  containing  the  MIDI  interface  to  be 
supported  by  the  driver  being  loaded.  Valid  values  range  from 
$0000  through  $0007. 
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slotFlag 


Indicates  whether  type  of  slot  specified  in  siotNumbe 


r: 


$0000 
$0001 


Internal  slot 
External  slot 


driverPath      Pascal  String  containing  the  GS/OS™  pathname  to  the  file 

containing  the  device  driver  to  be  loaded.  Pascal  strings  consist 
of  data  preceded  by  a  length  byte.  The  pathname  cannot  exceed 
64  characters  in  length. 
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Midilnfo  $0C20 

Returns  certain  information  about  the  state  of  the  MIDI  tools.  The  funcNum  parameter 
can  specify  nine  different  functions,  whose  results  are  returned  in  infoResult. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


funcNum 


Long— Space  for  result 

Word— Specifies  Midiinf  o  function  number 
<— SP 


Stack  after  call 


Previous  contents 


infoResult 


Long— Result  of  Midimf  o  function 
<— SP 

Errors  See  the  Mi di info  function  descriptions . 

C  extern  pascal  Long  Midiinf o (funcNum)  ; 

Word  funcNum; 

funcNum       Specifies  the  Midiinf  o  function  to  be  performed 

0  miNextPktLen 

Returns  the  number  of  bytes  in  the  next  MIDI  packet.  On  return, 
infoResult  contains  the  length  of  the  next  complete  MIDI  packet  in  the 
input  buffer,  including  the  four-byte  time-stamp  at  the  beginning  of  the 
packet.  Note  that  if  there  is  no  complete  packet  in  the  input  buffer,  this 
function  returns  a  value  of  0. 


Errors 

$2007 


miNoBufErr   No  buffer  allocated. 
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1  milnputChars 

Returns  the  number  of  bytes  of  MIDI  data  waiting  in  the  input  buffer.  On 
return,  infoResult  contains  the  number  of  bytes  of  MIDI  data  currently 
stored  in  the  input  buffer,  including  any  time-stamp  and  length  data  (6 
bytes  per  packet),  error  codes,  and  up  to  12  bytes  of  extra  space  at  the 
end  of  the  buffer  due  to  call  latency.  It  is  therefore  only  a  rough  estimate 
of  the  number  of  bytes  in  the  buffer.  Your  application  an  use  this  call  to 
monitor  whether  the  input  buffer  is  large  enough. 

Errors 

$2007         iniNoBuf  Err   No  buffer  allocated. 

2  miOutputChars 

Returns  the  number  of  bytes  of  MIDI  data  waiting  in  the  output  buffer. 
On  return,  infoResult  contains  the  number  of  bytes  waiting  to  be 
transmitted  from  the  MIDI  output  buffer,  including  time-stamp  and 
length  data  (6  bytes  per  packet),  error  codes,  and  up  to  12  bytes  of  extra 
space  at  the  end  of  the  buffer  due  to  call  latency.  It  is  therefore  only  a 
rough  estimate  of  the  number  of  bytes  in  the  buffer.Your  appliation  can 
use  this  call  to  monitor  whether  the  output  buffer  is  large  enough. 

Errors 

$2007         miNoBuf  Err   No  buffer  allocated. 

3  itdMaxInChars 

Returns  the  largest  number  of  bytes  that  were  stored  in  the  input  buffer 

since  the  last  miMaxinChars  call  or  since  the  buffer  was  last  flushed. 
This  call  is  especially  useful  for  deriving  statistics  on  buffer  utilization. 

Errors  None 

4  miMaxOutChars 

Returns  the  largest  number  of  bytes  that  were  stored  in  the  output  buffer 

since  the  last  miMaxOutchars  call  or  since  the  output  buffer  was  last 
flushed.  This  call  is  especially  useful  for  deriving  statistics  on  buffer 
utilization. 

Errors  None 

5  Not  yet  implemented 

6  Not  yet  implemented 
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7  miClockValue 

Returns  the  current  value  of  the  MIDI  Tool  Set  time-stamp  clock.  If  the 

clock  is  stopped  then  the  low-order  byte  of  the  result  is  0. 
Errors  None 

8  miClockFreq 

Returns  the  current  MIDI  Tool  Set  clock  frequency  in  ticks  per  second. 
The  default  value  is  13,l60  ticks  per  second. 

Errors  None 
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MidiReadPacket  $0D20 

Moves  MIDI  data  from  the  MIDI  Tool  Set's  input  buffer  to  a  specified  location  and 
returns  the  length  of  the  packet  in  bytes.  If  no  packet  is  available,  the  call  returns  a  0.  For 
more  information  on  MIDI  packets,  see  "MIDI  packet  format"  eariier  in  this  chapter. 

Parameters 

Stack  before  call 

Previous  contents 

Space  Word— Space  for  result 

buJPtr      -  Long— Pointer  to  buffer  for  received  data 

bufSize  Word— Length,  in  bytes,  of  the  receive  buffer 
<— SP 

Stack  after  call 


Previous  contents 


result 


Errors 


$2001 
$2002 


$2003 

$2007 
$2083 


$2084 
$2085 


Word— Number  of  bytes  actually  returned 
<— SP 


miPacketErr 
iniArrayErr 


miFullBufErr 

iniNoBufErr 
miDevOverrun 

miDevNoConnect 
miReadErr 


Incorrect  packet  length  received. 
Array  was  an  invalid  size.  The 
array  was  too  small  to  store  the 
next  packet.  Use  a  larger  array  or 
discard  the  packet  with  the 

MidiControl  Call. 

MIDI  data  discarded  because  of 

buffer  overflow. 

No  buffer  allocated. 

MIDI  interface  overrun  by  input 

data;  interface  not  serviced 

quickly  enough. 

No  connection  to  MIDI 

interface. 

Error  reading  MIDI  data. 
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extern  pascal  Word  MidiReadPacket (buf Ptr,  buf Size) ; 

Pointer  bufPtr; 
Word  bufSize; 


38-50    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


MidiWritePacket  $0E20 

Queues  the  specified  MIDI  packet  into  the  MIDI  Tool  Set's  output  buffer.  If  the  packet 
is  successfully  written  to  the  output  buffer,  this  call  returns  the  number  of  bytes  written.  If 
the  buffer  is  too  full  to  accommodate  the  packet,  MidiwritePacket  returns  0.  For 
more  information  on  MIDI  packets,  see  "MIDI  packet  format"  in  this  chapter. 

MidiWritePacket  returns  within  Hoof  a  second,  but  the  output  process  waits  until  the 
MIDI  clock  value  is  equal  to  or  greater  than  the  output  packet's  time-stamp  before 
sending  it.  Your  program  should  issue  this  call  before  before  starting  the  MIDI  output 
process  (with  the  mistartoutput  function  of  the  MidiControi  tool  call). 

In  packet  mode,  MidiwritePacket  assumes  that  only  complete  MIDI  commands  are 
passed  to  it,  and  that  the  first  byte  of  each  packet  is  a  MIDI  status  byte.  The  MIDI  Tool 
Set  uses  these  assumptions  to  track  NoteOn  and  NoteOff  commands,  In  raw  mode  the 
MIDI  Tool  Set  makes  no  attempt  to  track  NoteOn  and  NoteOff  commands,  so  the 
intelligent  NoteOff  function  provided  in  MidiControi  will  not  work,  and  packets  may 
contain  complete,  partial,  or  multiple  MIDI  commands.  In  either  mode  the  MIDI  Tool  Set 
omits  the  MIDI  status  byte  unless  its  value  has  changed  since  the  last  one  was  transmitted. 
You  can,  however,  disable  running  status  transmission  entirely  by  using  the  MidiControi 
call. 

If  the  MIDI  clock  is  stopped,  then  all  packets  with  a  time-stamp  less- than  or  equal  to  the 
value  of  the  clock  are  immediately  transmitted,  and  all  packets  with  a  value  greater  than 
the  clock  remain  in  the  buffer  unless  the  clock  is  restarted  and  its  value  becomes  greater 
than  the  time-stamps. 

Two  special  time-stamp  values  override  normal  output  buffer  processing,  irrespective  of 
MIDI  clock  state.  Any  packet  with  a  zero  time-stamp  is  written  immediately  upon 
reaching  the  head  of  the  output  buffer.  Any  packet  with  a  negative  time-stamp  value  is 
considered  to  be  a  real-time  command  and  the  packet  is  inserted  at  the  head  of  the 
output  queue  for  immediate  transmission.  Note  that  MIDI  real-time  messages  may  be 
transmitted  in  the  middle  of  non-real-time  MIDI  messages. 

The  MIDI  Tool  Set  routines  do  not  sort  the  packets  in  the  output  buffer,  therefore,  a 
packet  at  the  head  of  the  output  queue  can  delay  transmission  of  any  packets  behind  it 
that  have  eariier  time-stamp  values. 
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Parameters 

Stack  before  call 


Previous  contents 


Space 


bufPtr 


Stack  after  call 


Word— Space  for  result 

Long— Pointer  to  buffer  containing  output  data 
<— SP 


Previous  contents 


bytesWritten 


Errors 
C 


Word— Number  of  bytes  actually  written 
<— SP 

None 

extern  pascal  Word  MidiWritePacket (buf Ptr) ; 
Pointer  bufPtr; 
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MIDI  Tool  Set  error  codes 

This  section  lists  the  error  codes  that  may  be  returned  by  MIDI  Tool  Set  calls. 


Value  Name  Definition 


$2000  mistartupErr      MIDI  Tool  Set  not  started  up. 

$2001  miPacketErr        Incorrect  packet  length  received. 

$2002  iniArrayErr         Array  was  an  invalid  size. 

$2003  miFuiiBufErr      MIDI  data  discarded  because  of  buffer  overflow. 

$2004  miTooisErr         Required  tools  inactive  or  incorrect  version. 

$2005  mioutof fErr        MIDI  Output  disabled. 

$2007  iniNoBufErr         No  buffer  allocated. 

$2008  miDriverErr        Specified  device  driver  invalid. 

$2009  iniBadFreqErr      Unable  to  set  MIDI  clock  to  the  specified 

frequency  (use  the  Midi  info  tool  call  to  get  the 

current  value). 

$200A  miciockErr  MIDI  clock  wrapped  to  0. 

$200B  miconf  lictErr     Two  processes  competing  for  MIDI  input. 

$200C  miNoDevErr         No  device  driver  loaded. 

$2080  miDevNotAvaii     MIDI  interface  not  available. 

$2081  itiiDevSiotBusy     Specified  slot  not  selected  in  Control  Panel. 

$2082  miDevBusy  MIDI  interface  already  in  use. 

$2083  miDevOverrun       MIDI  interface  overrun  by  input  data;  interface 

not  serviced  quickly  enough. 
$2084  miDevNoConnect    No  connection  to  MIDI  interface. 

$2085  iniDevReadErr      Error  reading  MIDI  data. 

$2086  miDevVersion      ROM  version  or  machine  type  incompatible  with 

device  driver. 

$2087  itiiDevintHndir     Conflicting  interrupt  handler  installed. 
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Chapter  39  Miscellaneous  Tool  Set  Update 


This  chapter  documents  new  features  of  the  Miscellaneous  Tool  Set.  The 
complete  reference  to  the  Miscellaneous  Tools  is  in  Volume  1,  Chapter  14 
of  the  Apple  IIGS  Toolbox  Reference. 
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Error  corrections 

■  On  page  14-58  of  the  Toolbox  Reference,  Figure  14-3  shows  the  low-order  bit  of  the  User 
ID  is  reserved.  This  is  not  correct,  The  figure  should  show  that  the  mainiD  field 
comprises  bits  0-7,  and  that  the  mainiD  value  of  $00  is  reserved. 

■  The  sample  code  on  page  14-28  contains  an  error.  In  the  code  to  clear  the  1  second  IRQ 
source,  the  second  instruction  reads 

TSB  $C032 

This  instruction  should  read 

TRB  $C032 

■  The  descriptions  of  the  PackBytes  and  unPackBytes  tool  calls  are  unclear  with 
respect  to  the  startHandle  parameter  to  each  call.  The  stack  diagrams  correctly 
describe  the  parameter  as  a  pointer  to  a  pointer.  However,  the  C  sample  code  for  each 
call  defines  startHandle  3&  a  handle.  In  bodi  cases,  startHandle  is  not  a  Memory 
Manager  handle,  but  is  a  pointer  to  a  pointer.  Creating  startHandle  as  a  handle  will 
cause  unpredictable  system  behavior. 


New  features  in  the  Miscellaneous  Tool  Set 

■  ciearHeartBeat  and  DeieteHeartBeat  will  turn  off  the  interrupts  that  occur 
every  60th  of  a  second  if  the  following  conditions  are  satisfied: 

□  There  are  no  remaining  heartbeat  tasks. 

□  The  interrupt  handler  installed  in  IRQ.VBL  is  the  standard  system  interrupt  handler, 
that  is,  no  other  interrupt  handlers  have  been  installed. 

□  The  standard  mouse  is  not  running  in  VBL  interrupt  mode. 

■  setvector  and  Getvector  support  several  new  vectors.  The  new  vectors  are: 

$80  Vector  to  memory  mover 

$81  Vector  to  set  system  speed 

$82  Vector  to  slot  arbiter 

$86  Hardware  independent  interrupt  vector 

$87  MIDI  intermpt  vector  (IRQ-MIDI) 

♦  Note:  Setvector  no  longer  validates  the  input  vector  number.  Therefore,  you  must 
be  extremely  careful  when  using  this  all  in  order  to  avoid  cornipting  memory. 
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Queue  handling 

The  Miscellaneous  Tool  Set  now  provides  a  generalized  queue  handler  that  can  be  used  by 
other  tools  and  applications.  A  queue  is  defined  here  as  an  ordered  collection  of  variable- 
length  data  elements.  Each  data  element  must  be  preceded  by  a  standard  queue  header. 
Your  application  must  format  the  queue  elements  and  format  the  correct  header.  The 
queue  handler  provides  calls  to  add  or  remove  elements  from  a  queue  (AddToQueue  and 
DeleteFromQueue). 

A  queue  is  identified  by  its  header  pointer,  a  pointer  to  the  first  element  in  the  queue. 
Your  application  establishes  and  maintains  the  header  pointer.  Do  not  add  this  first 
element  to  the  queue  with  AddToQueue. 

Figure  39-1  shows  the  format  of  the  queue  header. 


■   Figure  39-1     Queue  header  layout 


$00 

—  Reserved 

Long— Link  to  next  item  in  queue— set  by  queue  handler 

$04 

—  Reserved 

Word— Reserved  for  system  use 

$06 

—  signature 

Word— Validates  header-^nust  be  set  to  $A55A 

Application  data  immediately  follow  the  header. 

See  "New  Miscellaneous  Tool  Set  calls"  later  in  this  chapter  for  details  on  AddToQueue 
and  DeleteFromQueue. 
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Interrupt  state  information 

The  Miscellaneous  Tool  Set  now  provides  a  set  of  calls  that  allow  you  to  obtain  interrupt- 
time  system  state  information.  These  calls  should  be  particularly  useful  to  developers  of 
debuggers  or  interrupt  handlers.  With  these  new  calls,  your  program  can  get  or  set  system 
interrupt  state  information. 

All  these  new  calls  use  a  standard  interrupt  state  record  Note  that  the  tool  calls  have  been 
designed  to  support  an  extensible  state  record.  In  the  future,  the  record  may  grow  in  size, 
but  existing  program  code  should  still  work. 

Figure  39-2  shows  the  format  of  the  interrupt  state  record.  For  more  information  about 
any  of  these  registers,  see  the  Apple  IIGS  Firmware  Reference. 


m   Figure  39-2     Interrupt  state  record  layout 


$00 

-             lrq_A  - 

Word— A  register  contents 

$02 

-              irq_X  - 

Word— X  index  register  contents 

$04 

-             lrq_Y  - 

Word— Y  index  register  contents 

$06 

-             lrq_S  - 

Word— S  (stack)  register  contents 

$08 

-             lrq_D  - 

Word— D  (direa)  register  contents 

$0A 

lrq_P 

Byte— P  (program  status)  register  contents 

$0B 

irq_DB 

Byte— DB  (data  bank)  register  contents 

$0C 

irq_e 

Byte— Bit  0  is  the  emulation  mode  bit 

$0D 

lrq_K 

Byte— K  (program  bank)  register  contents 

$0E 

-            irq_PC  - 

Word— PC  (program  counter)  register  contents 

$10 

irq_state 

Byte— STATEREG  byte  value 

$11 

—        lrq_shadow  — 

Word-SHADOW  byte  Oow  byte)  and  CYAREG  (high  byte)  values 

$13 

irqjnslot 

Byte-5LTR0MSELbyte 
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New  Miscellaneous  Tool  Set  calls 

The  following  sections  introduce  several  new  Miscellaneous  Tool  Set  calls. 


AddToQueue  $2E03 

Adds  the  specified  entry  to  a  queue. 

Parameters 

Stack  before  call 


Previous  contents 


-   newEntryPtr  - 


headerPtr 


Stack  after  call 


Previous  contents 


Errors 


$0381 
$0382 


Long— Pointer  to  element  to  add  to  queue 
Long— Pointer  to  first  queue  element 
<— SP 


<— SP 
invalidTag 

alreadylnQueue 


Signature  value  invalid  in  element 
header 

Specified  element  already  in 
queue 


extern  pascal  void  AddToQueue (newEntryPtr, 
headerPtr) ; 


Pointer      newEntryPtr,  headerPtr; 
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DeleteFromQueue  $2F03 

Deletes  a  specified  element  from  a  queue, 

Parameters 

Stack  before  call 


Previous  contents 


entryPtr 


headerPtr 


Stack  after  call 


Previous  contents 


Errors 


$0380 
$0381 


Long— Pointer  to  element  to  delete  from  queue 

Long— Pointer  to  first  queue  element 
<— SP 


<— SP 
notlnList 

invalidTag 


Specified  element  not  found  in 
queue 

Signature  value  invalid  in  element 
header 


extern  pascal  void  DeleteFromQueue (entryPtr, 
headerPtr) ; 


Pointer      entryPtr,  headerPtr; 
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GetCodeResConverter  $3403 

Returns  the  address  of  a  routine  that  loads  code  resources.  This  is  a  Miscellaneous  tool  call 
because  the  loader  is  not  in  directly  accessible  memory  (it  lives  in  the  bank  1  language 
card,  which  may  or  may  not  be  addressable  at  any  given  time). 

Your  program  would  use  this  call  in  conjunction  with  the  ResourceConverter  Resource 
Manager  tool  call  (see  Chapter  45,  "Resource  Manager,").  For  example,  the  Control 
Manager  issues  the  following  call  during  its  startup  processing: 

ResourceConverter (GetCodeResConverter ( )  , 
rCtlDefProc, 

LogConverterln+SysConverterList ) ; 

After  issuing  this  call,  all  future  calls  to  the  Resource  Manager  to  load  resources  of  type 
rCtiDef  Proc  will  use  the  Miscellaneous  tools  routine  to  bring  the  resource  into  memory. 
Note  that  this  routine  does  not  preserve  preserve  the  memory  attributes  of  the  converted 
resource  (for  more  information  on  resource  converters,  see 
Chapter  45,  "Resource  Manager,"  later  in  this  book). 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Long— Space  for  result 
<— SP 


Previous  contents 


pointer 


Long— Pointer  to  code  resource  converter  routine 
<— SP 


Errors 
C 


None 


extern  pascal  Pointer  GetCodeResConverter () ; 
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GetlnterruptState  $3103 


Copies  the  specified  number  of  bytes  into  a  specified  input  interrupt  state  record  from 
the  system  interrupt  variables.  The  copy  always  starts  from  the  beginning  of  the  interrupt 
state  record.  Use  the  setmterruptstate  call  to  set  the  contents  of  the  system 
interrupt  state  record. 

Parameters 

Stack  before  call 

Previous  contents 

-  intStateRcdPtr  -  Long— Pointer  to  interrupt  state  record 

bytesDesired  Word— Number  of  bytes  to  copy  from  system  to  record 
<— SP 

Stack  after  call 


Previous  contents 


Errors 
C 


<— SP 


None 


extern  pascal  void  GetlnterruptState (intStateRcdPtr, 
bytesDesired) ; 

Pointer  intStateRcdPtr; 
Word  bytesDesired; 
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GetlntStateRecSize  $3203 

Returns  the  size  (in  bytes)  of  the  internipt  state  record.  This  call  allows  application 
programs  to  work  with  extended  interrupt  state  records. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


sizeOjRecord 


Word— Length  of  interrupt  state  record,  in  bytes 


<— SP 


Errors 


None 


C 


extern  pascal  Word  GetlntStateRecSize () ; 


GetROMResoufce  $3503 


This  call  is  only  for  use  by  system  firmware 


Chapter  39  Miscellaneous  Tool  Set  Update  39-9 


Apple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


ReadMouse2  $3303 

Returns  the  mouse  position,  status,  and  mode.  This  call  does  not  support  joumaling.  Refer 
to  Chapter  14,  "Miscellaneous  Tool  Set,"  in  Volume  1  of  the  Toolbox  Reference  for 
information  about  the  ReadMouse  tool  call, 

A  Warning     Applications  should  never  make  this  call.A 


Parameters 

Stack  before  call 


PreiHous  contents 


Space 


Space 


Space 


Stack  after  call 

Previous  contents 


xPosition 


yPosition 


statusMode 


Errors 
C 


$0309 


Word— Space  for  result 
Word— Space  for  result 
Word— Space  for  result 
<— SP 


Word— X  position  of  mouse 
Word— Y  position  of  mouse 
Word— Status  and  mode  bytes 
<— SP 


unCnctdDevErr 


Pointing  device  is  not  connected 


extern  pascal  MouseRec  ReadMouse2 ( ) ; 


ReleaseROMResource  $3603 

This  call  is  only  for  use  by  system  firmware 
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SetlnterruptState  $3003 

Copies  the  specified  number  of  bytes  from  the  input  interrupt  state  record  into  the 
system  interrupt  variables.  The  copy  always  starts  from  the  beginning  of  the  interrupt 
state  record.  Use  the  Getmterruptstate  call  to  read  the  system  interrupt  state 
record. 

Parameters 

Stack  before  call 


Previous  contents 


-  intStateRcdPtr  - 


bytesDesired 


Stack  after  call 


Long— Pointer  to  interrupt  state  record 

Word— Number  of  bytes  to  copy  from  record  to  system 

<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  SetlnterruptState (intStateRcdPtr, 
bytesDesired) ; 


Pointer  intStateRcdPtr; 
Word  bytesDesired; 
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Chapter  40  Note  Sequencer 


This  chapter  documents  the  Note  Sequencer.  This  is  new  documentation, 
not  previously  presented  in  the  Apple  IlGS  Toolbox  Reference. 
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About  the  Note  Sequencer 

The  Note  Sequencer  is  a  collection  of  routines  that  implement  a  sequencer  in  the 
Apple  IlGS.  The  sequencer  is  an  interpreter  for  a  simple  music  programming  language 
designed  to  play  music  in  the  background.  It  can  be  used  to  play  music  from  a  static  file 
as  long  as  any  other  active  system  tasks  do  not  disable  interrupts. 

This  sequencer  plays  melodies  by  using  data  stored  in  a  specific  format.  It  does  not 
provide  the  means  to  create  these  data  structures,  and  so  an  application  must  provide  its 
own  tools  for  building  new  sequences. 

The  Note  Sequencer  works  with  the  Note  Synthesizer,  and  it  can  work  with  the  MIDI  tools 
if  you  choose. 

♦  Note:  The  Note  Synthesizer,  the  Note  Sequencer,  and  the  MIDI  Tool  Set  refer  to  the 
software  tools  provided  with  the  Apple  IlGS,  not  to  any  separate  instrument  or 
device.  The  MIDI  tools  are  software  tools  for  use  in  controlling  external  instalments, 
which  may  be  connected  through  a  MIDI  interface  device. 
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Using  the  Note  Sequencer 

To  use  the  Note  Sequencer,  you  must  have  loaded  the  following  tool  sets 

■  Tool  Locator 

■  Memory  Manager 

■  Sound  Tool  Set 

■  Note  Synthesizer 

■  MIDI  Tool  Set  (if  MIDI  is  to  be  used) 

All  the  required  tool  sets  must  be  started  up  except  the  Sound  Tool  Set  and  the  Note 
Synthesizer.  The  Note  Sequencer  makes  the  appropriate  calls  to  start  up  these  two  tool 
sets.  Refer  to  Chapter  51,  "Tool  Locator  Update,"  for  information  on  the  specific  version 
requirements  of  the  Note  Sequencer. 

The  Note  Sequencer  is  interrupt-driven  and  can  run  in  the  background  while  other 
application  tasks  take  place  in  the  foreground.  Therefore,  interrupts  must  not  be  disabled 
while  a  sequence  is  being  played.  Any  activity  that  disables  interrupts  interferes  with 
execution  of  a  sequence.  Disk  access,  for  example,  disables  interrupts,  so  an  application 
cannot  simultaneously  gain  access  to  a  disk  and  play  a  sequence  with  the  Note  Sequencer. 
Note  as  well  that  any  custom  error  and  completion  routines  your  application  provides  to 
the  Note  Sequencer  (see  "Error  handlers  and  completion  routines"  in  this  chapter)  also  run 
with  intermpts  disabled  and  with  a  very  low  stack. 

An  application  can  normally  rely  on  the  Note  Sequencer's  built-in  functions  to  synchronize 
a  sequence  correctly.  For  those  applications  that  must  directly  control  the  timing  of 
sequence  execution,  the  stepSeq  call  has  been  provided.  This  call  enables  an  application 
to  explicidy  control  the  execution  of  a  sequence  one  step  at  a  time. 


Sequence  timing 

Normally  you  might  think  of  a  musical  sequence  as  several  independent  tracks  playing  at 
the  same  time.  For  example,  a  musical  passage  might  consist  of  a  violin  sound  playing  a 
melody  accompanied  by  a  viola  and  a  flute.  Musically,  the  three  instruments  will  often  play 
at  once,  sounding  different  notes.  The  Note  Sequencer,  however,  always  plays  notes  in 
sequence,  one  after  another,  however  many  instruments  it  is  using  to  play  them. 
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A  chord,  which  is  musically  a  group  of  different  notes  played  at  the  same  time,  is  executed 
by  the  Note  Sequencer  as  a  series  of  discrete  notes  played  very  quickly  one  after  the 
other.  For  example,  the  Note  Sequencer  would  play  a  chord  consisting  of  F  above  middle 
C,  A  above  middle  C,  and  C  one  octave  above  middle  C  as  a  series  of  note  commands: 


If  the  Note  Sequencer  waited  for  each  note  to  finish  before  beginning  the  next  one,  the 
resulting  passage  would  be  three  distinct  notes  of  equal  length,  which  is  not  what  was 
intended.  The  Note  Sequencer  therefore  provides  a  way  to  play  the  three  notes  with  very 
little  delay  between  them;  so  little,  in  fact,  that  they  sound  as  though  they  were  being 
played  all  at  once. 

If  the  chord  bit  is  set  to  1  in  a  note  command,  it  indicates  that  the  next  note  should  be 
played  to  sound  a  chord  with  the  current  one.  If,  on  the  other  hand,  the  delay  bit  is  set 
to  1,  it  indicates  that  the  current  note  must  be  completed  before  the  next  one  is  played. 


Using  MIDI  with  the  Note  Sequencer 

The  appropriate  calls  must  be  made  to  the  MIDI  Tool  Set  to  use  MIDI  with  the  Note 
Sequencer.  Specifically,  the  MIDI  tools  must  be  started  up,  a  device  driver  must  be 
selected,  and  a  MIDI  output  buffer  must  be  allocated  (see  Chapter  38,  "MIDI  Tool  Set,"  in 
this  book  for  details).  In  addition,  you  must  start  the  MIDI  output  process  by  issuing  the 
miStartOutput  function  of  the  MidiControl  tOol  cali. 

You  must  specify  whether  MIDI  is  to  be  used  when  you  start  up  the  Note  Sequencer.  If  the 
high  bit  of  the  mode  parameter  is  set  when  the  seqstartup  call  is  made,  then  MIDI  is 
enabled.  If  a  particular  track  is  to  use  MIDI,  it  must  be  enabled  for  that  track,  using  the 
setTrkinf  o  call.  Finally,  the  Note  Sequencer  checks  tool  call-specific  and  seqltem- 
specific  flags  for  MIDI  information,  so  that  individual  tool  calls  or  commands  can  enable 
or  disable  MIDI. 

If  all  the  appropriate  flags— the  mode  flag,  the  track  flag,  and  the  command  or  tool  call 
flag— are  enabled,  then  MIDI  commands  are  sent  to  external  MIDI  devices.  This 
arrangement  is  designed  to  provide  flexibility  in  execution.  You  could,  for  example,  play 
only  the  drum  parts  of  a  sequence  on  external  MIDI  instruments,  by  enabling  MIDI  output 
only  on  the  appropriate  tracks,  or  you  could  play  all  parts  on  external  MIDI  instruments. 
Switching  between  the  two  modes  of  play  would  not  require  any  modification  of  the 
sequence  itself. 


Note 


Duration 


F4 
A4 
C5 


4  counts 
4  counts 
4  counts 
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The  Note  Sequencer  as  a  command  interpreter 

The  Note  Sequencer  is  actually  a  command  interpreter.  The  commands  it  interprets  are  32- 
bit  data  structures  called  seqitems,  or  sequence  items.  These  32-bit  items  contain 
information  that  the  Note  Sequencer  needs  to  classify  them  as  note  commands,  control 
commands,  MIDI  commands,  or  register  commands,  and  to  execute  them  properly. 

The  format  of  a  seqitem  is  detailed  in  Figure  40-1. 


■   Figure  40-1     Format  of  a  seqitem 
Bits 


31 

16 

15 

14 

8 

7 

6 

0 

tail 

n 

vail 

chord 

cmd 

cmd  For  all  commands  except  note  commands,  this  is  the  command 

identifier,  a  7-bit  number  that  uniquely  identifies  the  command.  For 
example,  the  vibrato  depth  command  has  a  cmd  value  of  4. 

chord  The  chord  bit  is  a  Boolean  value.  If  set,  it  specifies  that  the  Note 

Sequencer  should  immediately  execute  the  next  seqitem  with  no 
delay. 

vail  The  meaning  of  the  vaii  field  depends  on  the  command  being 

issued. 

note  The  note  bit  identifies  note  commands.  If  bit  n  is  set,  the  seqitem  is 

a  note  command. 

tail  The  format  of  the  tail  field  depends  upon  the  command  type.  It 

contains  two  or  more  fields  with  command-specific  information  in 
them. 

There  are  four  types  of  seqitems:  note  commands,  control  commands,  MIDI  commands, 
and  register  commands.  Each  type  is  organized  in  the  same  way,  but  the  values  in  each 
part  of  the  data  structure  have  different  meanings  in  the  different  commands. 
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Error  handlers  and  completion  routines 

The  Note  Sequencer  provides  facilities  allowing  application  programs  to  gain  control  at 
the  end  of  a  sequence,  and  when  any  errors  are  encountered  during  sequence  processing. 
The  Note  Sequencer  invokes  completion  routines  when  it  has  finished  a  sequence.  The 
completion  routine  can  then  perform  any  necessary  application-specific  processing. 
Similarly,  when  an  error  occurs  during  sequence  processing,  the  Note  Sequencer  calls  a 
specified  error  handler,  which  can  process  the  error  in  a  manner  appropriate  to  the  current 
application. 

When  you  start  a  sequence  with  the  startseq  tool  call,  you  may  specify  a  completion 
routine,  an  error  handler,  or  both  for  the  sequence.  The  compRoutine  parameter  points  to 
the  completion  routine;  the  errHndlrRoutine  parameter  specifies  the  error  Handler.  Zero 
values  for  either  parameter  indicate  to  the  Note  Sequencer  that  there  is  no  custom  routine 
of  the  appropriate  type  available. 

On  entry  to  either  type  of  routine,  the  Note  Sequencer  sets  up  the  following  conditions: 

■  Interrupts  disabled 

■  Direct  page  set  for  Note  Sequencer  data  area 

■  Data  bank  set  to  its  value  at  the  time  of  initial  seqstartup  tool  call  for  the 
application;  Note  Sequencer  restores  this  value  when  the  routines  return 

■  All  registers  saved 

■  Very  little  stack  available 

When  a  sequence  started  by  startSeq  reaches  its  end,  control  will  pass  to  the  routine 
specified  by  compRoutine. 

Whenever  an  error  is  encountered  during  sequence  processing,  the  Note  Sequencer  will  try 
to  call  the  error  handler  for  the  sequence.  A  useful  function  of  an  error  handler  might  be  to 
place  an  error  flag  for  the  completion  routine  and  make  a  GetLoc  call  to  determine  the 
location  of  the  error. 

The  Note  Sequencer  passes  error  codes  to  the  error  handler  in  the  A  register.  In  step  mode, 
the  Note  Sequencer  will  both  report  the  error  condition  to  the  error  handler  and  post  it  in 
the  A  register  at  the  completion  of  the  call  to  stepseq.  In  interrupt  mode,  the  Note 
Sequencer  will  only  report  the  error  to  the  application  error  handler. 

♦  Note:  The  Note  Synthesizer's  timer  oscillator  is  not  forced  on  when  an  error  occurs  in 
the  StartSeq  call;  neither  the  Note  Synthesizer  nor  the  Sound  Tool  Set  will  have  been 
started. 
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Note  commands 


Note  commands  switch  notes  on  and  off.  You  can  use  note  commands  in  two  ways.  You 
can  issue  a  pair  of  NoteOn  and  NoteOff  commands,  turning  a  specified  note  on  at  a 
certain  point  and  then  explicitly  turning  it  off,  or  you  can  issue  a  NoteOn  command  with  a 
duration  specified.  In  this  case  the  Note  Sequencer  plays  the  note  for  a  number  of  ticks 
equal  to  the  value  of  the  duration  parameter,  then  turns  the  note  off  without  the  need  for 
an  explicit  NoteOff  command.  Each  tick  occurs  at  an  interval  set  by  the  Note 
Synthesizer's  update  rate  (see  Chapter  41,  "Note  Synthesizer,"  in  this  book  for  details). 


■   Figure  40-2     Note  command  format 


Bits 

31  30 


27  26 


16    15  14 


d 

trk 

duration 

n 

pitch 

chord 

volume 

volume 


chord 


pitch 


note 


duration 


Specifies  note  volume.  Corresponds  to  MJDl  velocity.  A  value  of  0 
indicates  a  NoteOff  command. 

Indicates  that  the  seqitem  is  to  be  played  simultaneously  with  the 
next  seqitem.  Do  not  set  both  the  chord  bit  and  the  delay  bit  in  the 
same  item. 

Selects  the  pitch  to  be  played.  Values  may  range  from  0  to  127.  A  value 
of  60  selects  middle  C  (261.6  Hz).  Adjacent  values  are  one  semitone 
apart.  A  value  of  0  specifies  a  filler  note  (see  "Filler  notes"  in  this 
chapter  for  details). 

Always  set  to  1  for  note  commands.  If  this  bit  is  not  set  to  1  in  a 
seqitem,  then  the  seqitem  is  not  a  note  command. 

Specifies  the  length  of  time  the  Note  Sequencer  is  to  play  the  note. 
Values  may  range  from  0  to  2047,  and  specify  the  number  of  ticks  the 
note  is  to  be  played. 

A  duration  of  0  identifies  the  seqitem  as  a  NoteOn  command.  A 
NoteOn  seqitem  is  played  continuously  until  the  Note  Sequencer 
finds  a  matching  NoteOff. 
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trk  Track  number.  Assigns  notes  to  synthesizer  voices  and  MIDI  cliannels 

by  specifying  their  track  numbers.  Values  from  $0  to  $F  are  legal.  Refer 
to  the  description  of  the  Set  Trk  info  call  for  more  information. 

delay  If  this  bit  is  set  to  1,  the  Note  Sequencer  must  finish  playing  this 

seqitem  before  beginning  to  play  the  next  one.  The  Note  Sequencer 
cannot  advance  to  the  next  seqitem  until  the  duration  is  past.  Do 
not  set  this  bit  to  1  if  the  chord  bit  is  set  to  1. 


Filler  notes 

Filler  notes  are  used  to  fill  spaces  in  musical  sequences.  Intuitively,  you  might  suppose 
that  an  application  should  use  delays  to  create  rests,  but  during  a  delay  the  Note 
Sequencer  delays  all  its  operations.  Not  only  does  it  not  play  any  notes  until  the  delay 
period  has  elapsed,  it  also  does  not  perform  other  services,  such  as  turning  notes  off.  You 
could  cause  strange  behavior  in  a  sequence  if  you  used  delays  to  create  rests. 

An  alternative  approach  is  to  use  filler  notes.  A  filler  note  is  simply  a  note  command  with  a 
pitch  value  of  0.  Such  a  note  will  be  played  by  the  Note  Sequencer  as  though  it  were  an 
ordinary  note,  but  will  not  produce  a  tone.  You  can  therefore  use  filler  notes  to  fill  out 
rests  where  you  might  have  supposed  a  delay  would  be  needed.  For  example,  a  passage 
may  contain  a  chord  consisting  of  notes  with  different  duration,  followed  by  a  run  of 
other  notes.  In  this  case,  you  would  want  to  place  a  filler  note  at  the  end  of  the  chord,  so 
that  you  can  easily  vary  the  delay  between  the  start  of  the  chord  and  the  start  of  the  run. 


Filler  note  command 


volume  0 

chord  1 

pitch  Pitch  value  =  0 

note  1 

duration  Desired  delay  time 

trk  0 

delay  Set  to  1  if  a  delay  is  desired 
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NoteOff  command 


volume  Note  volume-0 

chord  Set  if  the  note  is  part  of  a  cliord 

pitch  0  to  127;  must  be  the  same  as  matching  NoteOn 

note  1 

duration  0 

trk  0-15;  must  be  the  same  as  matching  NoteOn 

delay  0 


NoteOn  command 


volume  Note  volume;  varies  from  1  to  127 

chord  Set  if  the  note  is  part  of  a  chord 

pitch  Pitch  value;  varies  from  0  to  127 

note  1 

duration  0 

trk  0-15 

delay  0 
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Control  commands 

Control  commands  are  used  to  specify  the  characteristics  of  the  Note  Sequencer  as  it  is 
playing  the  notes.  They  can  control  pitch  bend,  tempo,  vibrato,  and  other  note 
characteristics. 


■   Figure  40-3     Control  command  format 


Bits 

31  30        27  26      24  23  16   15    14  8      7       6  0 


d 

trk 

res 

val2 

n 

vail 

chord 

cmd 

cmd 
chord 

vail 
note 

val2 

reserved 

trk 

delay 


Command  number. 

The  chord  bit  should  be  set  to  1  in  a  control  command.  A  0  chord  bit 
can  sometimes  cause  unwanted  delays  in  playing  a  sequence. 

This  field  contains  data  specific  to  each  command. 

Always  set  tiiis  bit  to  0  for  control  commands.  A  note  bit  set  to  1 
causes  the  seqitem  to  be  processed  as  a  note  command  instead  of  a 
control  command. 

Contains  data  specific  to  each  command. 

Reserved  for  control  field.  These  bits  should  always  be  set  to  0  unless 
otherwise  specified. 

Notes  are  assigned  to  synthesizer  voices  and  to  handlers  by  specifying 
their  trk  nundjers.  Legal  values  are  $0  to  $F. 

The  delay  bit  should  always  be  set  to  0  in  control  commands,  since 
they  have  no  duration. 
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CallRoutine  command 


note 


vail 


cmd 


chord 


30 
1 
0 
0 


bits  16-23 
bits  24-31 


Low-order  byte  of  routine  address 
High-order  byte  of  routine  address 


This  command  allows  you  to  invoke  program  code  from  within  a  sequence  being  played 
by  the  Note  Sequencer.  This  program  code  is  then  free  to  perform  custom  processing.  The 
command  specifies  the  low-order  word  of  the  routine  address;  the  bank  portion  of  the 
address  matches  the  value  of  the  data  bank  register  at  the  time  the  Note  Sequencer  was 
started  by  your  application. 

On  entry,  interrupts  are  disabled  and  there  is  very  little  stack  space  remaining.  The  Note 
Sequencer  saves  its  registers  before  issuing  the  call.  However,  the  direct  page  and  data 
bank  registers  are  set  for  the  Note  Sequencer,  so  your  routine  code  must  change  these  in 
order  to  access  application  data.  The  routine  should  return  with  an  rtl  instruction. 

If  your  application  uses  MIDI,  this  routine  must  be  careful  to  poll  MIDI  every  270 
microseconds  to  avoid  losing  MIDI  data.  See  Chapter  38,  "MIDI  Tool  Set,"  in  this  book 
for  more  information. 
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Jump  command 


vail 


cmd 


chord 


3 
1 

vail  is  the  high  7  bits  of  the  destination 


delay 


note 


val2 


trk 


reserved 


0 

vai2  is  the  low  8  bits  of  the  Jump  destination 
0 

not  used 
0 


The  Jump  command  is  the  Note  Sequencer's  equivalent  of  a  jump  or  goto  command  in  a 
conventional  programming  language.  Execution  of  seqitems  will  continue  with  the  item 
specified  by  vaii  and  vai2.  The  number  given  is  a  simple  index  into  the  series  of 
seqitems  (it  is  not  a  byte  index  into  the  seqitem  array).  The  Jump  command  does  not 
check  the  bounds  of  the  sequence,  and  it  is  therefore  possible  to  jump  to  an  arbitrary  area 
in  memory  that  does  not  contain  valid  seqitems,  which  will  produce  unpredictable  results. 

Note  that  diis  command  causes  a  jump  in  the  sequence  being  processed.  To  jump  to 
executable  code  from  a  sequence,  use  the  CallRoutine  command. 


40-12    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Pitch  Bend  command 

cmd  0 
chord  1 

vail  Pitch  wheel  position.  Values  >  64  specify  sharp  pitch  bend;  values  <  64 

specify  flat;  intervals  are  expressed  in  fractions  of  the  current  pitch  bend 
range 

note  0 

vai2  No  significance  in  the  pitch  Bend  command;  the  val2  field  should  always 

be  set  to  0  for  Pitch  Bend 
reserved         Selects  pitch  bend  assignment 

0  selects  both  internal  and  MIDI  pitch  bend 

1  selects  internal  pitch  bend 

2  selects  MIDI  pitch  bend 
trk                Track  number 

delay  0 

The  Pitch  Bend  command  creates  a  bend  effect  in  a  played  note.  A  control  command 
expresses  pitch  bend  as  a  value  from  0  to  127.  A  value  of  64  indicates  no  pitch  bend,  and 
the  note  is  played  at  the  pitch  specified  in  its  note  command.  The  note  is  played  at  a 
pitch  determined  by  its  nominal  pitch  plus  the  pitch  bend  sharp  or  flat.  The  pitch  changes 
immediately  to  the  new  value.  As  a  result,  the  sequence  must  use  a  series  of  Pitch  Bend 
commands  to  achieve  the  smooth  portamento  usually  associated  with  a  pitch  bend. 

The  reserved  field  indicates  whether  the  pitch  bend  is  to  affect  the  system's  internal 
voices,  external  MIDI  devices,  or  both.  Note  that  your  application  must  have  specified 
MIDI  support  at  Seqstartup  time  in  order  for  MIDI  commands  to  be  issued. 
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Program  Change  command 


cmd 

chord 

vail 

note 

val2 

reserved 


trk 


delay 


5 
1 

Instrument  index  from  instalment  table 
0 

New  MDI  program  number,  if  the  sequence  is  using  MIDI 
Specifies  MIDI  usage;  legal  values  are 

0  The  Apple  IIGS  internal  synthesizer  and  an  external  MIDI  device 

1  The  Apple  IlGS  internal  synthesizer  only 

2  External  MIDI  device  only 

Track  number;  specifies  which  instrument  program  to  change  by 
specifying  the  track  to  which  that  instrument  is  assigned 
0 


The  Program  Change  command  allows  a  sequence  to  change  the  instmment  assigned  to  a 
track  during  play.  The  new  instrument  must  be  in  the  current  instalment  table  for  the  new 
assignment  to  be  possible. 

If  MIDI  is  enabled  and  the  reserved  field  specifies  that  a  MIDI  command  is  to  be 
issued,  the  Note  Sequencer  generates  a  MIDI  Program  Change  command  using  vai2  for 
the  program  number. 


Tempo  command 


cmd  1 

chord  1 

vail  New  increment;  he  value  may  vary  from  0  to  127 

note  0 

val2  0 

reserved  0 

trk  0 

delay  0 


This  command  sets  the  Note  Sequencer's  increment  value.  The  increment  value  determines 
the  number  of  ticks  between  updates  in  the  execution  cycle,  so  larger  increments  translate 
to  slower  tempos.  The  increment  value  is  set  to  its  initial  value  by  the  seqstartup  tool 
call. 
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Turn  Notes  Off  command 


cmd  2 

chord  1 

vail  0 

note  0 

val2  0 

reserved  0 

trk  0 

delay  0 


This  command  turns  off  all  notes  currently  being  played,  overriding  any  previous  note 
commands.  If  MIDI  support  has  been  enabled,  the  system  also  turns  off  any  active  MIDI 
notes. 


Vibrato  Depth  command 


cmd  4 

chord  1 

vail  The  new  value  for  vibrato  depth;  the  value  may  vary  from  0  to  127 

note  0 

vai2  Control  number  if  a  MIDI  command  is  generated 

reserved  0;  internal  and  MIDI  vibrato;  1:  internal  only 

trk  Track  number 

delay  0 


The  Vibrato  Depth  command  assigns  a  depth  value  to  the  vibrato  effect  used  with  the 
specified  track.  The  vibrato  effect  is  a  modulation  in  the  pitch  of  the  voice  assigned  to 
the  specified  track.  The  vaii  value  can  range  from  0  to  127,  with  larger  values  resulting  in 
greater  vibrato  depth.  A  value  of  0  disables  vibrato,  which  conserves  CPU  cycles. 

If  MIDI  support  has  been  enabled  and  the  reserved  field  indicates  that  a  MIDI 
command  is  to  be  issued  as  well,  vai2  specifies  the  MIDI  control  number,  and  vaii 
specifies  the  new  vibrato  value  for  the  MIDI  Control  Change  command. 
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Register  commands 

Register  commands  provide  the  Note  Sequencer  with  program  control  capabilities.  The 
Note  Sequencer  maintains  eight  8-bit  pseudoregisters  that  can  be  used  to  implement 
looping  and  conditional  branching  structures.  With  register  commands,  an  application  can 
achieve  the  effect  of  control  structures  such  as  "if... then,"  "do... while,"  or  "repeat... until" 
in  sequences. 

Each  register  occupies  8  bits  of  memory,  but  not  all  the  commands  use  the  full  register. 
The  IfGo  Register  and  Set  Register  commands  treat  each  register  as  if  it  were  only  4  bits  in 
size,  using  only  the  least  significant  4  bits  of  the  byte. 

Bytes  2  through  9  of  the  Note  Sequencer's  direct  page  contain  the  pseudoregisters;  these 
pseudoregisters  are  numbered  0  through  7.  Note  that  Note  Sequencer  direct-page  space 
starts  $100  bytes  beyond  the  location  specified  at  seqstartup  time.  The  intervening 
space  is  used  by  the  Note  Synthesizer  and  the  Sound  Tool  Set. 

■   Figure  40-4     Register  command  format 


Bits 

31  30       27  26     2423  16   15    14  8      7      6  0 


d 

trk 

res 

val2 

n 

vail 

chord 

cmd 

cmd  Command  number. 

chord  The  chord  bit  should  be  set  to  1  in  a  register  command.  A  0  chord 

bit  can  sometimes  cause  unwanted  delays  in  playing  a  sequence. 

vail  Contains  data  specific  to  each  command.  Generally  specifies  the 

register  number  for  the  command. 

note  Always  set  this  bit  to  0  for  register  commands.  A  note  bit  set  to  1 

causes  the  seqitem  to  be  processed  as  a  note  command  instead  of  a 
register  command. 

vai2  Contains  data  specific  to  each  command. 

reserved         Reserved  for  control  field.  These  bits  should  always  be  set  to  0  unless 
otherwise  specified. 

trk  Always  set  to  0  for  register  commands. 
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delay  The  delay  bit  should  always  be  set  to  0  in  register  commands,  since 

they  have  no  duration. 


Dec  Register  command 

cmd  9 
chord  1 

vail  Low  3  bits  contain  the  register  number 

note  0 

val2  0 

reserved  0 

trk  0 

delay  0 

Decrements  the  value  of  the  specified  pseudoregister.  If  the  value  is  0  when  the  command 
is  executed,  the  pseudoregister's  value  will  wrap  to  $FF. 


IfGo  Register  commiand 

cmd  7 
chord  1 

vail  Low  3  bits  contain  the  register  number 

High  4  bits  contain  the  value 
note  0 

vai2  Offset:  -128  to  +127  seqitems 

reserved  0 
trk  0 
delay  0 

Tests  the  specified  pseudoregister  for  the  specified  value.  If  the  pseudoregister  contains 
the  supplied  value,  then  execution  continues  with  the  seqitem  at  the  offset  specified  in 
vai2,  calculated  from  the  current  seqitem.  If  the  values  do  not  match,  execution 
continues  with  the  next  seqitem  in  sequence.  The  IfGo  Register  command  does  not  check 
the  bounds  of  the  offset  provided,  so  the  value  must  be  a  valid  one,  or  the  effects  will  be 
unpredictable. 
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Inc  Register  command 

cmd  8 

chord  1 

vail  Low  3  bits  contain  the  register  number 

note  0 

val2  0 

reserved  0 

trk  0 

delay  0 

Increments  the  value  of  the  specified  pseudoregister. 


Set  Register  command 

cmd  6 
chord  1 

vail  Low  3  bits  contain  the  register  number 

High  4  bits  contain  the  value 
note  0 
val2  0 
reserved  0 
trk  0 
d  0 

Sets  the  specified  pseudoregister  to  the  specified  value. 
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MIDI  commands 

MIDI  commands  enable  an  executing  sequence  to  send  data  direcdy  to  MIDI  devices  diat 
are  connected  to  the  Apple  IIGS.  All  the  standard  MIDI  commands  are  provided. 

For  MIDI  commands  to  be  enabled,  the  high  bit  of  the  mode  parameter  must  be  set  when 
the  Seqs  tart  Up  call  is  made.  To  produce  MIDI  output,  your  application  must  also  have 
loaded  and  started  up  the  MIDI  Tool  Set.  For  further  information  on  the  MIDI  Tool  Set, 
see  Chapter  38,  "MIDI  Tool  Set,"  in  this  book. 

These  commands  are  based  on  version  1.0  of  the  MIDI  specification,  version  1.0,  which  is 
not  described  in  this  documentation. 


■   Figure  40-5     MIDI  command  format 


Bits 

31  2423  16   15  14  8      7      6  0 


high 

low 

n 

vail 

chord 

cmd 

cmd  Command  number. 

chord  The  chord  bit  should  be  set  to  1  in  a  MIDI  command.  A  0  chord  bit 

can  sometimes  cause  unwanted  delays  in  playing  a  sequence. 

vail  Contains  data  specific  to  each  command, 

note  Always  set  this  bit  to  0  for  MIDI  commands.  A  note  bit  set  to  1 

causes  the  seqitem  to  be  processed  as  a  note  command  instead  of  a 
MIDI  command. 

low  Contains  data  specific  to  each  command. 

high  Contains  data  specific  to  each  command. 
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MidiChannelPressure  command 


cmd  15 

chord  1 

vail  Bits  8  through  1 1  are  the  channel  number 

note  0 

low  Channel  pressure 

high  0 


Sends  a  ME)I  Channel  Pressure  command  to  the  channel  specified  in  vaii.  The  new 
pressure  value  is  specified  by  the  low  byte. 


MidiControlChange  command 


cmd  13 

chord  1 

vail  Bits  8  through  11  are  the  channel  number 

note  0 

low  Control  number 

high  Control  value 


Sends  a  MIDI  Control  Change  command  to  the  channel  specified  in  vail.  The  control 
number  is  specified  in  the  low  byte  and  the  control's  new  value  is  in  the  high  byte. 


MidiNoteOff  command 


cmd  10 

chord  1 

vail  bits  8  through  11  are  the  channel  number 

note  0 

low  Note  number 

high  Velocity 


Sends  a  MIDI  NoteOff  command  on  the  channel  number  specified  in  vaii.  The  note 
turned  off  is  specified  in  two  parts— a  note  number  in  the  low  byte  and  a  velocity  in  the 
high  byte. 
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MldiNoteOn  command 


cmd  11 

chord  1 

vail  Bits  8  through  11  are  the  channel  number 

note  0 

low  Note  number 

high  Velocity 


Sends  a  MIDI  NoteOn  command  on  the  channel  number  specified  in  vaii.  The  note 
turned  on  is  specified  in  two  parts— a  note  number  in  the  low  byte  and  a  velocity  in  the 
high  byte. 


MidlPitchBend  command 


cmd  l6 

chord  1 

vail  Bits  8  through  11  are  the  channel  number 

note  0 

low  Pitch  bend  least  significant  byte 

high  Pitch  bend  most  significant  byte 


Sends  a  MIDI  Pitch  Bend  command  to  the  channel  specified  by  vaii.  The  new  pitch 
bend  value  is  specified  by  the  high  word  of  the  command,  with  the  least  significant  byte 
of  the  value  in  the  low  byte  and  the  most  significant  byte  in  the  high  byte. 
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MidiPolyphonicKeyPressure  command 


cmd  12 

chord  1 

vail  Bits  8  through  11  are  the  channel  number 

note  0 

low  Note  number 

high  Key  pressure 


Sends  a  MIDI  Polyphonic  Key  Pressure  command  on  the  channel  number  specified  in 
vail,  The  note  affected  is  specified  as  a  note  number  in  the  low  byte  of  the  high  word, 
Its  new  key  pressure  is  in  the  high  byte 


MidiProgramChange  command 


cmd  14 

chord  1 

vail  Bits  8  through  1 1  specify  the  MIDI  channel  number  ($0-$0F) 

note  0 

low  Program  number 

high  0 


Sends  a  MIDI  Program  Change  command  to  the  channel  specified  in  vaii.  The  program 
number  is  specified  in  the  low  byte. 


MidiSelectChannelMode  command 


cmd  17 

chord  1 

vail  Bits  8  through  11  are  the  channel  number 

note  0 

low  First  data  byte 

high  Second  data  byte 


Sends  a  MIDI  Select  Channel  mode  command  to  the  channel  specified  in  vaii.  The  new 
MIDI  channel  mode  is  specified  by  two  data  bytes,  the  first  of  which  is  passed  in  the  low 
byte  and  the  second  in  the  high  byte. 
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MidiSetSysExlHighWord  command 


vail 


note 


cmd 


chord 


21 
1 
0 
0 


high 


low 


Low  byte  of  high  word 
High  byte  of  high  word 


The  MIDI  System  Exclusive  command  passes  a  two-word  address  to  its  target.  That 
address  is  a  pointer  to  a  MIDI  packet.  The  high  word  of  the  address  is  specified  by  this 
command,  while  the  low  word  is  specified  by  the  MidiSystemExclusive  command.  The 
MidiSetSysExlHighWord  command  must  precede  the  MidiSystemExclusive  command. 
See  the  discussion  of  that  command  for  more  information  about  the  format  and  content 
of  the  MIDI  packet. 


MidiSystemExclusive  command 

cmd  18 

chord  1 

vail  0 

note  0 

low  Least  significant  byte  of  low  word  of  MIDI  packet  address 

high  Most  significant  byte  of  low  word  of  MIDI  packet  address 

The  MIDI  System  Exclusive  command  passes  a  two-word  address  to  its  target.  That 
address  is  a  pointer  to  a  MIDI  packet.  The  low  word  of  the  address  is  specified  by  this 
command,  while  the  high  word  is  specified  by  the  MidiSetSysExlHighWord  command. 
The  MidiSetSysExlHighWord  command  must  precede  the  MidiSystemExclusive 
command. 
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Here  is  an  example  of  a  3-byte  System  Exclusive  command. 


$00 

—            length  — 

Word— Length  of  data  to  follow;  must  be  set  to  8 

$02 

$06 

tlmeStamp 

4  Bytes— Time-stamp  for  send  time;  0  for  immediate  send 

sysExclusive 

Byte— System  Exclusive  flag  byte;  must  be  set  to  $F0 

$07 

datal 

Byte— First  MIDI  data  byte 

$08 

data2 

Byte— Second  MIDI  dau  byte 

$09 

data3 

Byte— Third  MIDI  data  byte 

MidiSystemCommon  command 

cmd  19 
chord  1 

vail  Bits  8  through  10— low  nibble  of  status  byte 

value  varies  from  1  through  7 
Bits  11  and  12— number  of  data  bytes: 

00  -  0  data  bytes 

01  - 1  data  byte 

10  -  2  data  bytes 

11  -  invalid  value 

note  0 

low  First  data  byte 

high  Second  data  byte  (if  appropriate) 

Sends  one  or  two  bytes  of  MIDI  data.  The  first  data  byte  is  passed  in  the  low  byte  and 
the  second  data  byte,  if  there  is  one,  is  passed  in  the  high  byte. 


40-24    Apple  IIGS  Toolbox  Reference,  Volume  3 


Appk  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


MidiSystemRealTime  command 


cmd  20 

chord  1 

vail  0 

note  0 

low  Real-time  number  ($01-$07) 

high  0 


Sends  a  MIDI  System  Real-Time  command.  The  real-time  number  is  specified  in  the  low  3 
bits  of  the  low  byte. 
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Patterns  and  phrases 

A  pattern  is  any  series  of  seqitems.  The  Note  Sequencer  plays  melodies  by  carrying  out  the 
seqitem  commands  in  specified  patterns.  A  phrase  is  an  ordered  set  of  pointers  to 
patterns  or  to  other  phrases.  Since  a  phrase  can  contain  pointers  to  other  phrases,  it  is 
possible  to  nest  phrases.  The  Note  Sequencer  supports  up  to  12  levels  of  phrase  nesting. 

Phrases  and  patterns  have  a  similar  layout.  Both  phrases  and  patterns  are  preceded  by  a 
longword  header.  For  phrases,  this  header  is  set  to  1;  for  patterns,  the  header  is  set  to  0. 
The  Note  Sequencer  can  distinguish  between  phrases  and  patterns  by  examining  this 
header  value.  The  last  longword  in  both  phrases  and  patterns  must  be  set  to  $FFFFFFFF, 
and  is  called  the  phrase  done  flag. 

When  a  program  calls  the  Note  Sequencer  to  play  a  sequence,  it  passes  a  parameter 
containing  a  handle  to  the  first  byte  of  the  top-level  phrase.  This  phrase  consists  of  an 
ordered  series  of  pointers  to  the  patterns  or  phrases  to  be  played,  followed  by  a  longword 
value  ($FFFFFFFF)  that  marks  the  end  of  a  pattern  or  phrase. 

Each  pattern  consists  of  an  ordered  series  of  seqitems.  The  seqitems  describe  the 
characteristics  of  each  note  to  be  played  in  the  sequence.  Control  and  register  commands 
allow  the  characteristics  of  the  notes  to  be  modified  and  also  allow  the  programmer  to 
build  complex  sequences  by  using  conditional  looping  and  branching.  In  this  sense,  the 
Note  Sequencer  is  a  simple  programming  language. 

The  following  paragraphs  introduce  a  sample  phrase  and  a  sample  pattern,  so  that  you  can 
see  the  similarities  in  their  structure. 

A  phrase  is  identified  by  a  header  value  of  1 

topPhrase      dc        12 '0001'  ;  low  word 


The  phrase  body  consists  of  a  series  of  pointers.  Each  pointer  can  point  either  to  other 
phrases  or  to  patterns,  which  are  sequences  of  executable  seqitems.  For  example. 


dc 


i2'0000' 


;  high  word 


dc  i4'phrasel' 
dc  i4'patternl' 
dc  i4'phrase2' 


A  phrase  always  ends  with  a  phrase  done  flag: 

dc  i4'$FFFFFFFF' 


A  pattern  is  identified  by  a  header  value  of  0 
patternl        dc        12 '0000' 


low  word 


dc        12 '0000' 


high  word 
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The  body  of  a  pattern  consists  of  seqitems,  such  as; 

dc        14 ' $880ABC74 '  ;  play  C4,  duratlon=10,  volume=115 

dc        14 ' $880ABE74 •  ;  play  D4,  duratlon=10,  volume=115 

dc        14 ' $880AB074 '  ;  play  E4,  duration=10,  volume=115 

Again,  the  pattern  must  end  with  a  phrase  done  flag: 

dc  14'$FFFFFFFF' 


Chapter  40  Note  Sequencer  40-27 


Apple  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


A  sample  Note  Sequencer  program 

The  following  example  contains  65816  assembly  language  source  code  for  a  simple  Note 
Sequencer  program. 


mcopy 


s  .m 


DPPointer  gequ  $10 

DPHandle  gequ  $14 

HelpingHand        gequ  $18 


;  for  dereferencing  handles 


******************************************************* 


Main 


Start 
Using 


Common 


same 


clc 
xce 
long 
phk 

plb 


; set  Native  mode 


; Set  the  data  bank  to  the 


;as  the  program  bank 


jsl  StartTools 

jsl  MakeWaves 

jsl  Setlnstruments 

jsl  PlaySequence 

jmp  Cleanup 


StartTools 


_TLStartUp 
pha 

_MMStartUp 
pi  a 

sta  MylD 


;  Tool  Locator 

;  space  for  ID  returned 
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MakeWaves 


Trianglel 


PushLong 

#0 

Get  direct  page  for  tools 

PushWord 

#0 

PushWord 

#$600 

PushWord 

MylD 

PushWord 

#$C005 

direct  page 

PushLong 

#0 

_NewHandle 

pla 

sta 

HelpingHand 

pla 

sta 

HelpingHand+2 

Ida 

[HelpingHand] 

sta 

DPPointer 

pha 

PushWord 

#0 

either  320  or  640  mode 

PushWord 

#0 

max  size  of  scan  line 

PushWord 

MylD 

_QDStartup 

PushLong 

#ToolTable 

_LoadTools 

Ida 

DPPointer 

clc 

adc 

#$300 

QuickDraw  used  $300  bytes 

pha 

Pushword 

#0 

Pushword 

#$200 

Pushword 

#$10 

_SeqStartup 

starts  Synth&Sound  Tools 

rtl 

Idx 

#0 

r 

index  thru  SoundBuffer 

Ida 

#1 

base  of  triangle 

sta 

SoundBuf f er 

inx 

1 

step  thru  buffer 

sta 

SoundBuf f er,x 

inc 

A 

t 

slope  up  in  triangle 

cmp 

#$ff 

1 

byte  limit  for  sound  data 

bne 

Trianglel 
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Triangle2 


xnx 
dec 
sta 
cmp 
bne 
inx 
sta 
inx 
sta 
inx 
sta 


SoundBuf f er , X 
#$01 

Triangle2 
SoundBuf fer,  x 
SoundBuf fer,x 
SoundBuf fer,  X 


;   start  down  slope 


;  dont  want  zeros 


;  pad  3  bytes  with  1 


MakeTooth 
Sawtoothl 


Idy 
Ida 
inx 
sta 
dec 
bne 
dey 
bne 
Ida 
inx 
sta 
inx 
sta 


#2 

#$ff 

SoundBuf fer ,  X 
A 

Sawtoothl 

MakeTooth 
#1 

SoundBuf fer,  X 
SoundBuf fer,  x 


;  make  2  teeth 
;  start  high 


;  ramp  down 


;  do  2nd  tooth 


;  pad  last  2  bytes 


Squarel 


Idy 
Ida 
inx 
sta 
dey 
bne 


#255 
#1 

SoundBuf fer,  x 
Squarel 


;  make  a  square  wave 


Square2 


Idy 
Ida 
inx 
sta 
dey 
bne 


#255 
#255 

SoundBuf fer,  x 
Square2 
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Noisel 


NotZero 


Idy 
inx 
phy 
phx 
pha 

_Randoin 

pla 

bne 

inc 

plx 

ply 

sta 

inx 

inx 

dey 

bne 


#256 


;  noise  wave 


NotZero 
A 


SoundBuf f er ,  X 


;   space  for  random  result 


Noisel 


PushLong  #SoundBuffer 
PushWord  #$100 
PushWord  #$800 
WriteRamBlock 


;DOC  start  address 
;byte  count 


rtl 


Setlnstruments  Pushlong  #InstTableHandle 

_SetInstTabl 

Idx  #3 
TrackLoop  phx 

Pushword  #64 

phx 

phx 

_SetTrkInf o 

plx 

dex 

bpl  TrackLoop 
rtl 


;  do  4  tracks 


;  push  the  priority 
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PlaySequence 


PushLong  #0 
PushLong  #0 
PushLong  #Sequence 
_StartSeq 


No  Error  Handler  Routine 
No  Completion  Routine 


PushWord  #0 
PushWord  #0 
_ReadChar 
pla 


Pushword    #0  ;  No  Next  Phrase 

_StopSeq 

rtl 


Cleanup  _SeqShutdown 
_EMShutdown 
_QDShutdown 
PushWord  MylD 
_DisposeAll 
Quit  QuitParams 


End 

********************************************************* 
Common  Data 

QuitParams  dc  14" 0,0,0'  ;  Quit  back  to  calling  program 

MylD  ds  2 

tooltable  dc  i'2,26, 0,25, 0'   ;  two  tools,  numbers  26  &  25 

SoundBuffer      .  ds  2048 
InstTableHandle  dc  i4 ' InstTable ' 
InstTable  dc  i2M' 

dc      i4' Sawtooth' 

dc      i4' Square' 

dc      i4' Triangle' 

dc      i4' Noise' 


4  waves,   512  bytes  each 
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segment 


dc 

il 

127' 

envelope  breakpoint  1 

dc 

il 

0, 127  ' 

Increment  Value  1 

dc 

il 

120' 

breakpoint  2 

dc 

il 

20,1' 

increment  2 

dc 

il 

120' 

sustain  at  120 

dc 

il 

0,0' 

zero  increment  is  sustain 

dc 

il 

0' 

;  release  to  0  volume 

dc 

il 

60,12' 

;  slowly 

dc 

il 

0,0,0' 

;  pad  with  extra  breakpoint 

dc 

il 

0,0,0' 

;  increment  pairs  till  the 

dc 

il 

0,0,0' 

;  total  is  8 

dc 

il 

0,0,0' 

dc 

il 

3' 

;  release  segment  is  3rd  segment 

dc 

il 

32' 

;  priority  increment 

dc 

il 

2,80,90, 

0, 

1, 

1' 

;  pbrange,vibdep,vibf , spare,A,B 

dc 

il 

127,1,2, 

6, 

0, 

12' 

;  topkey, addr, size, Ctrl, pitch 

dc 

il 

127,1,2, 

1, 

0, 

12' 

;  halt  b,  to  be  swapped  in  by  a. 

dc 

il 

127' 

;  envelope  breakpoint  1 

dc 

il 

0,127' 

;  Increment  Value  1 

dc 

il 

120' 

;  breakpoint  2 

dc 

il 

20,1' 

;  increment  2 

dc 

il 

120' 

;   sustain  at  120 

dc 

il 

0,0' 

;   zero  increment  is  sustain 

segment 


dc 

il 

0* 

/ 

release  to  0  volume 

dc 

il 

60,12' 

f 

slowly 

dc 

il 

0,0,0' 

/ 

pad  with  extra  breakpoint 

dc 

il 

0,0,0' 

/ 

increment  pairs  till  the 

dc 

il 

0,0,0' 

/ 

total  is  8 

dc 

il 

0,0,0' 

dc 

il 

3' 

/ 

release  segment  is  3rd  segment 

dc 

il 

32' 

$ 

priority  increment 

dc 

il 

2,80,90, 

0, 

1, 

1' 

1 

pbrange, vibdep, vibf , spare, A, B 

dc 

il 

127,3,2, 

6, 

0, 

12' 

t 

topkey, addr, size, Ctrl, pitch 

dc 

il 

127,3,2, 

1, 

0, 

12' 

t 

halt  b,to  be  swapped  in  by  a. 
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segment 


dc 

il 

127' 

;  envelope  breakpoint  1 

dc 

il 

0,127' 

;   Increment  Value  1 

dc 

il 

120' 

;  breakpoint  2 

dc 

il 

20,1' 

;  increment  2 

dc 

il 

120' 

;   sustain  at  120 

dc 

il 

0,0' 

;   zero  increment  is  sustain 

dc 

il 

0' 

t 

release  to  0  volume 

dc 

il 

60,12' 

t 

slowly 

dc 

il 

0,0,0' 

$ 

pad  with  extra  breakpoint 

dc 

il 

0,0,0' 

1 

increment  pairs  till  the 

dc 

il 

0,0,0' 

t 

total  is  8 

dc 

il 

0,0,0' 

dc 

il 

3' 

release  segment  is  3rd  segment 

dc 

il 

32' 

1 

priority  increment 

dc 

il 

2,80,90, 

0, 

1, 

1' 

pbrange,vibdep, vibf , spare, A, B 

dc 

il 

127,5,2, 

0, 

12' 

f 

topkey, addr, size, Ctrl, pitch 

dc 

il 

127,5,2, 

1, 

0, 

12' 

f 

halt  b,to  be  swapped  in  by  a. 

segment 


dc 

il 

127' 

;  envelope  breakpoint  1 

dc 

il 

0,127' 

;   Increment  Value  1 

dc 

il 

120' 

;  breakpoint  2 

dc 

il 

20,1' 

;  increment  2 

dc 

il 

120' 

;   sustain  at  120 

dc 

il 

0,0' 

;   zero  increment  is  sustain 

dc 

il 

'0' 

f 

release  to  0  volume 

dc 

il 

60,12' 

t 

slowly 

dc 

il 

0,0,0' 

f 

pad  with  extra  breakpoint 

dc 

il 

0,0,0' 

1 

increment  pairs  till  the 

dc 

il 

0,0,0' 

t 

total  is  8 

dc 

il 

0,0,0' 

dc 

il 

3' 

$ 

release  segment  is  3rd  segment 

dc 

il 

32' 

t 

priority  increment 

dc 

il 

2,80,90, 

0, 

1, 

1' 

t 

pbrange, vibdep, vibf , spare, A, B 

dc 

il 

127,7,2, 

6, 

0, 

12' 

f 

topkey, addr, size, Ctrl, pitch 

dc 

il 

127,7,2, 

1, 

0, 

12' 

* 

halt  b,  to  be  swapped  in  by  a. 
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Delay 

Tl 

T2 

T3 

TO 

Qtr 

Half 

Note 

C4 

D4 

E4 

F4 

G4 

Chord 


equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 
ecju 
equ 
equ 
equ 
equ 


$80000000 
$08000000 
$10000000 
$18000000 
$0 

$40000 

$80000 

$8000 

$3C00 

$3E00 

$4100 

$4200 

$4300 

$80 


Sequence 
Phrasel 


do 
do 
dc 
do 
dc 
dc 
dc 
dc 


i4 'Phrasel ' 
14 '1' 

14 'Phrase2 ' 
14  'Patternl ' 
14 'Phrase2 ' 
14 'Patternl ' 
14 'Pattern2 ' 
14'$FFFFFFFF' 


;  phrase  header 


terminator 


Phrase2 


dc 
dc 
dc 
dc 


14'1' 

14 'Pattern2 ' 
14 'Patternl' 
14'$FFFFFFFF' 


;  phrase  header 


;  terminator 


Patternl 


dc 
dc 
dc 
dc 
dc 
dc 


14 '0' 

14 'Delay+T0+Qtr+Note+C4+127 ' 
14 ' Tl+Qtr+Note+C4+Chord+127 ' 
14 ' Delay+Tl+Qtr+Note+G4+127 ' 
14 'Delay+T0+Half+Note+F4+127 ' 
14 ' $FFFFFFFF' 


pattern  header 
full  volume 


terminator 
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Pattern2  dc  14' 0'  ;  pattern  header 

dc  14 'T2+Note+G4+Chord+127 '  ;  note  on 

dc  14 'Note+Half '  ;  filler  note 

dc  14 'Delay+T2+Qtr+Note+F4+127 ' 

dc  14 'Delay+T3+Qtr+Note+D4+127 ' 

dc  14'T3+Note+G4+Chord+127'  ;  note  off 

dc  14 '2'  ;  allnotesoff 

dc  14 ' $FFFFFFFF'  ;  terminator 


End 
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Note  Sequencer  housekeeping  calls 

The  following  sections  discuss  Note  Sequencer  calls  that  perform  common  tool  set 
functions. 

SeqBootlnit  $011A 

Initializes  the  Note  Sequencer. 

▲  Warning     This  call  must  not  be  made  by  an  application.A 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
C  extern  pascal  void  SeqBootlnit () ; 
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SeqStartUp  $021A 


SeqStartUp  starts  up  the  Note  Sequencer  and  performs  all  the  necessary  initializations  for 
the  tool  set.  It  also  makes  startup  calls  to  the  Sound  Tool  Set  and  the  Note  Synthesizer,  so 
an  application  should  not  start  up  those  tool  sets  before  making  this  call. 

Your  application  must  make  sure  that  the  MIDI  Tool  Set  has  been  started  before  issuing 
this  call. 

Parameters 

Stack  before  call 


Previous  contents 


dPageAddr 


mode 


updateRate 


increment 


Word— Beginning  of  Note  Sequencer  direct  page 
Word— MIDI  flag 

Word— Rate  of  interrupt  generation 
Word— Number  of  interrupts  per  system  tick 
<— SP 


Stack  after  call 


PreiHous  contents 


Errors 


$1A03 
$1A07 


<— SP 
startedErr 

nsWrongVer 


Sound  Tool  Set  errors 
Note  Synthesizer  errors 


The  Note  Sequencer  is  already 
started  up. 

The  Note  Synthesizer  is  a  version 
that  is  incompatible  with  the 
Note  Sequencer. 
Returned  unchanged 
Returned  unchanged 


extern  pascal  void  SeqStartUp (dPageAddr,  mode, 
updateRate,  increment)  ; 


Word 


dPageAddr,  mode,  updateRate,  increment; 
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dPageAddr         Specifies  the  location  for  the  Note  Sequencer's  direct  page.  This 
direct  page  must  actually  be  three  pages  of  bank  zero  memory, 
starting  at  the  specified  address.  The  first  page  is  used  by  the  Note 
Synthesizer  and  Sound  Tool  Set,  and  the  other  two  by  the  Note 
Sequencer.  All  three  pages  must  be  locked  and  page-aligned. 

mode  Determines  whether  the  Note  Sequencer  will  operate  in  interrupt 

mode,  in  which  updates  are  performed  automatically  as  intermpts 
occur,  or  in  step  mode,  in  which  updates  occur  only  when  explicit  step 
commands  are  issued.  If  the  low  bit  of  mode  is  set  to  0,  then 
interrupts  are  used;  if  it  is  set  to  1,  then  step  mode  is  used. 

The  high  bit  of  the  mode  parameter  also  determines  whether  MIDI 
processing  is  enabled.  If  an  application  uses  MIDI  commands  or  wants 
to  support  automatic  generation  of  appropriate  MIDI  commands, 
then  the  high  bit  must  be  set  to  1. 

updateRate         Specifies  how  often  the  Note  Sequencer  will  update  its  actions,  using 
interrupts,  For  example,  an  updateRate  value  of  500  specifies  that  the 
Note  Sequencer  will  receive  interrupts  at  200  hertz,  or  every  5 
milliseconds.  A  value  of  250  means  that  interrupts  will  be  available  at 
100  hertz,  or  every  10  milliseconds  (500  is  the  default  value)  The  same 
rate  is  used  by  the  Note  Synthesizer  to  update  its  instruments' 
envelopes. 

increment  Specifies  how  many  interrupts  constitute  one  tick  of  the  Note 

Sequencer  counter.  If  updateRate  is  500  and  increment  is  20,  then  one 
tick  will  take  100  milliseconds.  The  Note  Sequencer  gets  interrupts 
every  5  milliseconds,  and  the  counter  is  incremented  every  20 
interrupts.  If  a  quarter  note  equals  5  ticks,  then  it  lasts  half  a  second, 
which  corresponds  to  a  tempo  of  120  beats  per  minute.  In  general,  you 
can  compute  the  number  of  beats  per  minute  by  using  the  following 
formula: 

B  -  (24  •  UpdateRate)  I  (.inaement  *T) 

B  is  beats  per  minute  and  T  is  the  number  of  ticks  in  a  beat. 

Typical  updateRate  values  might  be; 

60  Hz         60/0.4  =  150;  updateRate  =  150 
100  Hz        100/0.4  =  250;  updateRate  =  250 
200  Hz        200/0.4  =  500;  updateRate  =  500 
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Larger  values  for  updateRate  result  in  greater  control  of  a  sequence's 
tempo  and  smoother  envelopes.  On  the  other  hand,  a  higher 
UpdateRate  also  requires  more  processor  time  to  service. 

One  general  method  for  choosing  appropriate  updateRate  and 
increment  values  is  to  decide  on  the  shortest  note  you  will  want  to 
play.  Suppose  the  shortest  note  that  you  want  to  play  is  a  sixteenth 
note.  Assign  sixteenth  notes  a  value  of  1.  Eighth  notes  are  twice  as 
long,  so  assign  them  a  value  of  2.  Quarter  notes  then  receive  a  value  of 
4,  half  notes  8,  and  whole  notes  16.  Now  decide  how  long  you  want  a 
whole  note  to  be  and  compute  the  updateRate  znd  increment  so  that 
the  duration  comes  out  the  way  you  want  it. 

Once  you  have  set  the  updateRate  value,  it  remains  in  effect;  you  can 
only  change  it  by  making  the  Note  Synthesizer  NSSetupdateRate 
call,  or  by  shutting  down  and  restarting  the  Note  Sequencer.  You  can 
change  the  increment  \ziut,  and  the  Note  Sequencer  provides  tempo 
calls  that  vary  the  tempo  for  you. 
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SeqShutDown  $031A 

Shuts  down  the  Note  Sequencer  tool  set.  It  frees  any  buffers  that  the  tools  may  have 
allocated.  An  application  that  uses  the  Note  Sequencer  should  call  seqshutoown  before 
quitting. 

Parameters        This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  $1923      nsNotinit  The  Note  Synthesizer  has  not 

been  started. 

$1A05      nostartErr  The  Note  Sequencer  has  not  been 

started  up. 

$0812      noSAppinitErr  The  Sound  Tool  Set  was  not 

started  up. 

C  extern  pascal  void  SeqShutDown () ; 
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SeqVersion  $04lA 

Returns  the  version  number  of  the  Note  Sequencer  that  is  currently  in  use.  Refer  to 
Appendix  A,  "Writng  Your  Own  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference  for 
information  on  the  format  and  content  of  the  reOirned  versionNum  value. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


versionNum 


Word— Note  Sequencer  version  number 


<— SP 


Errors 


None 


C 


extern  pascal  Word  SeqVersion () ; 
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SeqReset  $051A 

Resets  the  Note  Sequencer.  seqReset  is  called  when  the  Apple  IIGS  system  is  reset.  All 
internal  notes  presently  being  played  are  turned  off. 

▲  Warning     This  call  must  not  be  made  by  an  application.A 
Parameters        This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

C  extern  pascal  void  SeqReset (); 
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SeqStatus  $06lA 

Returns  a  Boolean  flag  indicating  whether  or  not  the  Note  Sequencer  is  active.  If  the  tool 
set  is  active,  the  flag  is  nonzero;  otherwise  it  is  zero. 

♦  Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  seqStatus,  your  program  need  only  check  the 
value  of  the  returned  flag.  If  the  Note  Sequencer  is  not  active,  the  returned  value  will 
be  FALSE  (NIL). 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


activeFlag 


Word— Boolean;  TRUE  if  Note  Sequencer  is  active 


<— SP 


Errors 


None 


C 


extern  pascal  Boolean  SeqStatus (); 
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Note  Sequencer  calls 

The  following  sections  discuss  the  Note  Sequencer  tool  calls. 


Clearlncr  $0A1A 

Sets  the  Note  Sequencer's  increment  value  to  0,  halting  the  current  sequence,  and  returns 
the  previous  increment  value.  Setting  the  increment  to  0  does  not  disable  the  Note 
Sequencer's  interrupts,  so  envelopes  are  still  updated.  This  means  that,  although  the 
sequence  will  not  progress,  notes  being  played  when  the  increment  was  set  to  0  may  hang. 
This  call  is  valid  only  while  a  sequence  is  playing. 

You  might  try  using  seqAiiNotesof  f  and  ciearincr  when  you  want  to  stop  a 
sequence  and  be  able  to  start  it  again  easily.  A  sequence  stopped  in  this  way  can  easily  be 
restarted  widi  a  call  to  setincr. 

Parameters 

Stack  before  call 

Prmous  contents 


Space 


Word— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


Result 


Word— Previous  increment  value 


<— SP 


Errors 


None 


C 


extern  pascal  Word  Clearlncr () ; 
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GetLoc  $0C1A 


Returns  certain  information  about  the  sequence  that  is  playing.  This  call  provides  an  index 
to  the  seqitem  that  is  executing,  the  current  pattern,  and  the  nesting  level.  The  nesting 
level  indicates  how  deeply  control  has  passed  into  a  structure  with  phrases  nested  within 
phrases.  A  nesting  level  value  of  0  indicates  that  the  Note  Sequencer  is  playing  the  top- 
level  phrase. 

For  example,  if  the  Note  Sequencer  is  playing  the  third  seqitem  in  Pattern  1,  which  occurs 
in  Phrase  1,  then  GetLoc  returns  this  information: 

curPattltem  =  3 
curPhraseltem  =  1 
curLevel  "  1 


Parameters 

Stack  before  call 


Previous  contents 
Space 
Space 
Space 


Stack  after  call 


Word— Space  for  result 
Word— Space  for  result 
Word— Space  for  result 
<— SP 


Previous  contents 


curPhraseltem 


curPattltem 


curLevel 


Errors 
C 


Word— Current  pattern  in  phrase  specified  by  curLevel 
Word — Current  seqitem  in  pattern  specified  by  curPhraseltem 
Word— Nesting  level  for  current  phrase 
<— SP 


None 

extern  LocRec  GetLoc (); 
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GetTimer  $0B1A 

Returns  the  value  of  the  Note  Sequencer's  tick  counter.  While  the  counter  is  advancing, 
the  value  returned  is  necessarily  somewhat  inexact,  since  the  value  changes  as  the  call  is 
executed.  The  call  is  valid  only  while  a  sequence  is  playing. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


Result 


Word— Current  timer  value 


<— SP 


Errors 


None 


C 


extern  pascal  Word  GetTimer {); 
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SeqAllNotesOf f  $0D1A 

Switches  off  all  notes  that  are  playing,  but  does  not  stop  the  sequence.  Thus,  any  notes 
that  are  held  are  turned  off,  but  the  sequence  continues.  Use  this  call  to  temporarily 
silence  all  instrument  voices  while  a  sequence  is  active.  If  the  high  bit  of  the  mode 
parameter  is  set,  then  the  Note  Sequencer  also  turns  off  all  external  MIDI  notes  of  which  it 
is  aware. 

Parameters        This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  None 

C  extern  pascal  void  SeqAllNotesOf f () ; 
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Setlncr  $091A 

Sets  the  Note  Sequencer's  increment  value.  An  application  can  use  this  facility  to  control 
the  tempo  of  a  sequence.  If  the  increment  value  is  set  to  0,  the  sequence  will  halt. 

Parameters 

Stack  before  call 


Previous  contents 


increment 


Word— Desired  increment  value 
<— SP 


Stack  after  call 


Previous  contents 


<— SP 

Errors  None 

C  extern  pascal  Setlncr (increment) ; 


Word 


increment; 
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SetlnstTable  $121A 

Sets  the  current  instrument  table  to  the  one  specified  in  instTable. 

Parameters 

Stack  before  call 


Previous  contents 


instTable 


Stack  after  call 


Long— Handle  to  instrument  table 
<— SP 


Previous  contents 


Errors 
C 

instTable 


<— SP 
None 

extern  pascal  void  SetlnstTable (instTable) ; 
Handle  instTable; 

The  instTable  parameter  is  a  handle  to  an  instrument  table.  The 
instrument  table  is  a  data  structure  in  Apple  IIGS  memory  that 
contains  pointers  to  one  or  more  instruments.  The  format  of  an 
instrument  table  is  as  follows: 


$00 

—  InstNumber 

$02 

instArray 

instArray         '■  Array  oflongs — InstNumber  pointers  to  instruments 


Note  that  the  first  pointer  in  the  array  corresponds  to  instrument  0. 
See  Chapter  41,  "Note  Synthesizer,"  in  this  book  for  more  information 
about  instruments. 
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SetTrklnfo  $0E1A 

Assigns  instruments  in  the  current  instrument  table  to  logical  tracks,  and  determines  the 
priorities  of  the  instruments  so  that  the  Note  Sequencer  an  correctly  allocate  generators 
to  them.  An  application  should  call  setTrkinf  o  for  each  track  it  uses,  before  starting  to 
play  a  sequence. 

If  MIDI  was  enabled  when  the  Note  Sequencer  was  started  up,  then  setTrkinf  o  can  be 
used  to  enable  MIDI  output  on  particular  tracks.  If  the  most  significant  bit  of  the 
trackNum  parameter  is  set,  then  everything  played  on  the  specified  track  will  produce 
MIDI  output  on  the  channel  number  specified  by  the  second  most  significant  byte  of 
trackNum.  For  example,  a  trackNum  value  of  $8201  specifies  that  everything  played  on 
track  1  produces  MIDI  output  on  MIDI  channel  2. 

The  application  may  disable  the  internal  voices  of  the  Apple  IIGS  for  a  specified  track  by 
issuing  this  call  with  the  highest  bit  of  the  instlndex  parameter  set. 

You  must  make  a  setinstTabie  call  before  issuing  this  call. 

Parameters 

Stack  before  call 

Previous  contents 

priority  Word— Priority  value 

instlndex  Word— Index  number  for  instrument  (first  instrument  is  number  0) 

trackNum  Word— Track  number  for  instrument 
<— SP 

Stack  after  call 


Previous  contents 


Errors 


$1A06 


<— SP 
instBndsErr 


The  specified  intrument  number 
is  out  of  the  bounds  of  the 
instrument  table. 


extern  pascal  void  SetTrkinf o (priority,  instlndex, 
trackNum) ; 


Word 


priority,   instlndex,  trackNum; 
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Startlnts  $131A 

Enables  interrupts.  Use  this  call  to  restore  normal  functioning  after  a  call  to  stopints. 
Parameters        This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  None 

C  extern  pascal  Startlnts () ; 


40-52    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


StartSeq  $0F1A 

Starts  interpretation  of  a  series  of  seqitems  stored  at  the  address  specified  by  sequence. 
Parameters 
Stack  before  call 

Previous  contents 

-  errHndlrRoutine  Long— Pointer  to  error  handler 

-  compRoutine  -  Long— Pointer  to  completion  routine 

sequence     -  Long— Handle  to  sequence 
<— SP 

Stack  after  call 

Previous  contents 

Errors  $1921 
$1A00 

$1A01 
$1A02 
$1A04 

$1A05 
$2004 
$2007 
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<— SP 
nSNoneAvail 

noRoomMidiErr 


noCoinmandErr 

noRoomErr 

noNoteErr 

noStartErr 

miToolsErr 

itiiNoBufErr 


Note  Synthesizer  error:  no 
generator  is  available. 
The  Note  Sequencer  is  tracking 
32  notes  that  are  currently 
playing;  there  is  no  room  for  a 
MIDI  NoteOn. 

The  current  seqitem  is  not  valid 
in  its  context. 

The  sequence  is  nested  more  than 

twelve  levels  deep. 

Can't  find  the  note  for  a  NoteOff 

command. 

The  Note  Sequencer  has  not  been 
started  up. 

Required  tools  not  active  or 

wrong  version 

No  MIDI  output  buffer  is 

allocated. 
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C  extern  pascal  void  StartSeq(errHndlrRoutine, 

compRoutine,   sequence) ; 

Pointer      errHndlerRoutine,  compRoutine; 
Handle  sequence; 

errHndlrRoutine   The  errHandlrRoutine  parameter  is  a  pointer  to  an  error  handling 

routine  supplied  by  the  application  programmer.  If  errHndlrRoutine  is 
set  to  NIL,  then  Note  Sequencer  will  not  invoke  a  routine.  For 
information  about  error  handling  routines  for  the  Note  Sequencer,  see 
"Error  handlers  and  completion  routines"  in  this  chapter. 

compRoutine       The  compRoutine  parameter  points  to  a  routine  to  be  called  when 
startseq  reaches  the  end  of  a  sequence.  If  compRoutine  is  set  to 
ML,  then  Note  Sequencer  will  not  invoke  a  routine.  For  information 
about  completion  routines  for  the  Note  Sequencer,  see  "Error  handlers 
and  completion  routines"  in  this  chapter. 

sequence  The  sequence  parameter  is  a  handle  to  the  phrase  to  be  executed  by 

the  Note  Sequencer.  The  handle  passed  in  sequence  should  be  locked. 
If  the  Note  Sequencer  is  running  in  interrupt  mode,  as  specified  by  the 
woi/e  parameter  of  the  seqstartup  call,  then  the  Note  Sequencer 
will  simply  start  interpreting  seqitems.  If,  however,  the  mode 
parameter  specified  that  the  Note  Sequencer  start  up  in  step  mode, 
then  the  startseq  call  must  be  followed  by  a  series  of  calls  to 
stepseq  to  play  the  seqitems  individually. 
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StartSeqRel  $151A 

Starts  interpretation  of  a  series  of  seqitems  stored  at  the  address  specified  by  sequence. 
This  call  differs  from  startseq  in  that  it  uses  relative  addressing  from  the  beginning  of 
the  sequence.  That  is,  all  phrase  and  pattern  pointers  are  interpreted  as  offsets  from  the 
start  of  the  sequence,  rather  than  as  absolute  addresses.  As  a  result,  coding  phrases  and 
patterns  is  easier.  Following  the  call  description  you  will  find  a  code  sample  showing  how 
to  specify  these  relative  offsets. 

The  Note  Sequencer  uses  the  dereferenced  value  of  sequence  as  the  base  address  for  all 
phrases  and  patterns.  It  does  not  check  for  overflow,  and  does  not  support  negative 
offsets  from  the  specified  base  address. 

Parameters 

Stack  before  call 


Previous  contents 


-  errHndlrRoutine 


-  compRoutine  - 


sequence 


Long— Pointer  to  error  handler 

Long— Pointer  to  completion  routine 

Long— Handle  to  sequence 
<— SP 


Stack  after  call 


Previous  contents 


<— SP 
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Errors 


$1921 

nSNoneAvai  1 

Note  Synthesizer  error:  no 
generator  is  available. 

SlAOO 

n  oRo  OTtiMi  diE  rir 

X  X  \^  X         ^/XLIX  X^  Vi*  1^  X.J  x> 

The  Note  Sequencer  is  tracking 
32  notes  that  are  currently 
playing;  there  is  no  room  for  a 
MIDI  NoteOn. 

$1A01 

noCoinnianciE  r  r 

The  current  seqitem  is  not  valid 
in  its  context. 

noRoornErr 

twelve  levels  deep. 

$1A04 

noNoteErr 

Can't  find  the  note  for  a  NoteOff 
command. 

$1A05 

noStartErr 

The  Note  Sequencer  has  not  been 
started  up. 

$2004 

miToolsErr 

Required  tools  not  active  or 
wrong  version 

$2007 

itiiNoBufErr 

No  MIDI  output  buffer  is 
allocated. 

errHndlrRoutine 


extern  pascal  void  StartSeqRel (errHndlrRoutine, 
compRoutine,  sequence) ; 

Pointer      errHndlerRoutine,  compRoutine; 
Handle  sequence; 

The  errHandlrRoiUine  parameter  is  a  pointer  to  an  error  handling 
routine  supplied  by  the  application  programmer.  If  errHndlrRoutine  is 
set  to  NIL,  then  Note  Sequencer  will  not  invoke  a  routine.  For 
information  about  error  handling  routines  for  the  Note  Sequencer,  see 
"Error  handlers  and  completion  routines"  in  this  chapter. 

compRoutine      The  compRoutine  parameter  points  to  a  routine  to  be  called  when 
startseq  reaches  the  end  of  a  sequence.  If  compRoutine  is  set  to 
NIL,  then  Note  Sequencer  will  not  invoke  a  routine.  For  information 
about  completion  routines  for  the  Note  Sequencer,  see  "Error  handlers 
and  completion  routines"  in  this  chapter. 
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sequence  The  sequence  parameter  is  a  handle  to  the  phrase  to  be  executed  by 

the  Note  Sequencer.  The  handle  passed  in  sequence  should  be  locked. 
If  the  Note  Sequencer  is  running  in  interrupt  mode,  as  specified  by  the 
wio^ie  parameter  of  the  seqstartup  call,  then  the  Note  Sequencer 
will  simply  start  interpreting  seqitems.  If,  however,  the  mode 
parameter  specified  that  the  Note  Sequencer  start  up  in  step  mode, 
then  the  startseq  call  must  be  followed  by  a  series  of  calls  to 
stepSeq  to  play  the  seqitems  individually. 
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Sample  sequence  with  relative  addressing 

The  following  example  is  a  sequence  presented  in  65816  assembly  language,  showing  how 
to  set  up  relative  addressing  for  startSeqRei. 


Delay  equ  $80000000 

Tl  equ  $08000000 

T2  equ  $18000000 

qtr  equ  $40000 

hlf  equ  $80000 

Note  equ  $8000 

C4  equ  $3C00 

D4  equ  $3E00 

F4  equ  $4100 

G4  equ  $4300 

Chord  equ  $80 


phrhndl  dc  14 'phrl-phrhndl' 

phrl  dc  14 '01'  ;  it's  a  phrase 

dc  i  4 ' ph r 2 -ph r hndl ' 

dc  14 'patl-phrhndl ' 

dc  14'phr2-phrhndl' 

dc  14 'patl-phrhndl ' 

dc  14'pat2-phrhndl' 

dc  14 ' $FFFFFFFF'  ;  end  of  phrase  1 


phr2  dc  14 '01'  ;  It ' s  a  phrase 

dc  14 ' pat2-phrhndl ' 

dc  14 'patl-phrhndl ' 

dc  14 ' $FFFFFFFF'  ;  end  of  phrase  2 

patl  dc  14 '00'  ;  It's  a  pattern 

dc  14'Delay+Tl+qtr+Note+C4+115' 

dc  14'Tl+qtr+Note+C4+Chord+115' 

dc  14'Delay+T2+qtr+Note+G4+115' 

dc  14'Delay+Tl+hlf+Note+F4+115' 

dc  14 ' $FFFFFFFF'  ;  end  of  patl 
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pat2  dc  14 '00'  ;  it's  a  pattern 

dc  i4'Tl+Note+G4+Chord+115'  ;  NoteOn 

dc  i4'Note+hlf'  ;   filler  note 

dc  i4'Delay+T2+qtr+Note+F4+115' 

dc  i4'Delay+T2+qtr+Note+D4+115' 

dc  i4'Tl+Note+G4+Chord+115'  ;  NoteOff 

dc  14" $00000002'  ;  AllNotesOff 

dc  14 ' $FFFFFFFF'  ;  end  of  pat2 
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StepSeq  $101A 

Increments  the  Note  Sequencer  counter,  causing  the  appropriate  seqitems  in  the  current 
sequence  to  be  processed.  A  stepSeq  call  is  the  equivalent  of  one  tick  of  the  Note 
Sequencer  counter,  which  consists  of  a  number  of  interrupts  equal  to  the  value  of  the 
increment  parameter  of  the  seqstartup  call. 

Parameters        This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

Errors  $1921      nsNoneAvaii  Note  Synthesizer  error:  no 

generator  is  available. 
$1A01      noCoitimandErr  The  current  seqitem  is  not  valid 

in  its  context. 

$1A02      noRoomErr  The  sequence  is  nested  more  than 

twelve  levels  deep. 

$1A04      noNoteErr  Can't  find  the  note  for  a  NoteOff 

command. 

C  extern  pascal  void  StepSeq (); 
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Stoplnts  $141A 

Disables  Note  Synthesizer  and  Note  Sequencer  interrupts. 

If  the  Note  Sequencer  is  started  up,  and  interrupts  are  enabled,  the  Note  Synthesizer  calls 
the  Note  Sequencer  interrupt  handler  whenever  an  interrupt  occurs.  When  no  notes  are 
being  played,  the  overhead  involved  in  this  processing  is  unnecessary,  so  stopints 
provides  a  way  to  cause  the  Note  Synthesizer  not  to  service  the  interrupts.  To  restart 
interrupt  processing,  use  the  startints  call. 

The  startseq  Call  Starts  interrupt  processing  automatically,  and  the  seqshutoown 
automatically  halts  it.  No  other  Note  Sequencer  call  affects  interrupt  processing  except 
stoplnts,  startints,  and  SeqShutDown. 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  None 

C  extern  pascal  void  Stoplnts (); 
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StopSeq  $111A 

Halts  interpretation  of  a  phrase.  The  next  parameter  specifies  whether  execution  should 
continue  if  there  are  more  phrases  to  be  executed  in  the  current  sequence.  If  so,  the  next 
phrase  begins.  Otherwise,  the  sequencer  simply  stops  and  calls  the  application's 
completion  routine.  See  "Error  handlers  and  completion  routines"  in  this  chapter  for  more 
information  on  completion  routines.  If  next  is  not  equal  to  0,  then  the  current  phrase 
terminates  and  execution  continues  with  the  next  phrase. 

If  any  notes  are  turned  on  with  NoteOn  commands,  and  a  call  to  stop seq  halts  the  phrase 
in  which  they  occur,  they  could  continue  to  play  forever,  waiting  for  NoteOff  commands 
that  will  never  occur.  You  should  thus  take  care  to  turn  off  any  such  notes  before  making  a 
call  to  StopSeq. 

Parameters 

Stack  before  call 

Previous  contents 


next 


Word— Boolean;  TRUE  to  process  remaining  phrases 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


None 


C 


extern  pascal  StopSeq (next) ; 


Boolean 


next  ; 
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Note  Sequencer  error  codes 

This  section  lists  the  error  codes  that  may  be  returned  by  Note  Sequencer  calls. 


Value  Name  Definition 


$1A00 

noRoomMidiErr 

The  Note  Sequencer  is  tracking  32  notes  that  are 
currently  playing;  there  is  no  room  for  a  MIDI 
NoteOn. 

$1A01 

noCoinmandErr 

The  current  seqitem  is  not  valid  in  its  context. 

$1A02 

noRoomErr 

The  sequence  is  nested  more  than  twelve  levels 

$1A03 

deep. 

startedErr 

The  Note  Sequencer  is  already  started  up. 

$1A04 

noNoteErr 

Can't  find  the  note  for  a  NoteOff  command. 

$1A05 

noStartErr 

The  Note  Sequencer  has  not  been  started  up. 

$1A06 

instBndsErr 

The  specified  intrument  number  is  out  of  the 
bounds  of  the  instrument  table. 

$1A07 

nsWrongVer 

The  Note  Synthesizer  is  a  version  that  is 
incompatible  with' the  Note  Sequencer. 
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Chapter  41  Note  Synthesizer 


This  chapter  documents  the  Note  Synthesizer.  This  is  new 
documentation,  not  previously  presented  in  the 
Apple  IlGS  Toolbox  Reference. 
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About  the  Note  Synthesizer 

The  Note  Synthesizer  is  a  tool  set  that  controls  operation  of  the  Apple  IIGS  Digital 
Oscillator  Chip  (DOC).  With  it,  an  application  can  turn  the  Apple  IIGS  into  a  digital 
synthesizer  for  playing  music  and  generating  sound  effects.  The  Note  Synthesizer 
provides  far  more  control  over  a  sound  than  the  Sound  Tool  Set,  and  supports  looping 
within  a  sound  sequence  and  enveloping  a  sound. 


Using  the  Note  Synthesizer 

An  application  that  uses  the  Note  Synthesizer  must  first  start  it  up  and  write  the  wave 
information  to  the  DOC  RAM  by  using  the  Sound  Tool  Sefs  writeRAMBiock  call,  then 
allocate  Digital  Oscillator  Chip  generators  for  its  use  with  AiiocGen.  It  can  play  musical 
notes  with  individual  calls  to  NoteOn  and  NoteOf  f  for  each  note  that  it  plays.  NoteOn 
starts  a  generator  and  the  process  that  automatically  updates  envelopes  as  it  plays  its 
assigned  instrument.  When  the  application  calls  Noteof  f ,  the  Note  Synthesizer  enters  the 
release  phase  of  the  envelope  for  that  generator,  and  the  note  begins  to  die  away. 

The  Note  Synthesizer  requires  that  the  Sound  Tool  Set  be  loaded  and  started  up. 


The  sound  envelope 

The  envelope  describes  the  graph  of  a  sound's  loudness  over  time.  The  terms  loudness, 
amplitude,  and  volume  all  refer  to  the  same  characteristic  of  a  sound.  In  addition,  the 
MIDI  quantity  velocity  is  normally  mapped  to  a  note's  loudness,  so  that,  for  instance,  the 
faster  a  key  on  a  keyboard  is  struck,  the  louder  its  corresponding  note  will  be.  A  note's 
envelope  is  what  gives  it  its  dynamic  quality.  A  short,  sharp  sound  has  a  steep,  short 
envelope,  and  a  long,  smooth  sound  has  a  flatter,  longer  envelope. 

A  synthesizer's  envelope  is  traditionally  described  in  terms  of  attack,  decay,  sustain,  and 
release,  or  ADSR.  Figure  41-1  shows  an  example  of  a  simple  envelope  described  in  terms 
of  ADSR. 
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■   Figure  41-1     Sound  envelope,  showing  attack,  decay,  sustain,  and  release 
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The  attack  portion  of  an  envelope  is  the  period  when  the  sound  is  increasing  from  silence 
to  its  peak  loudness.  This  part  of  the  envelope  determines  the  suddenness  of  a  sound.  A 
drumbeat  or  a  plucked  string  has  an  extremely  steep  attack,  whereas  a  bowed  string  or  a 
softly  blown  wind  instrument  has  a  much  flatter  attack. 

The  decay  part  of  the  envelope  is  die  period  when  the  sound  falls  off  from  its  peak 
loudness  to  the  level  it  stays  at,  which  is  its  sustain  portion.  Attack  and  decay  together 
can  be  used  to  control  a  sound's  percussiveness.  Sounds  with  a  steep  attack  and  decay 
tend  to  sound  plucked  or  percussive.  A  steep  attack  followed  by  a  flat  decay,  or  by  little 
or  no  decay,  blares  like  a  loud  trumpet.  A  very  flat  attack  and  decay  produce  a  sound  with 
a  soft,  smooth  quality. 

Sustain  determines  die  note's  overall  perceived  loudness  and  duration.  A  drumbeat  has 
virtually  no  sustain  or  release;  it  consists  almost  entirely  of  attack  and  decay.  A  long,  slow 
note  on  a  violin,  on  die  other  hand,  might  have  a  very  flat  attack  and  decay,  and  a  long, 
high  sustain. 

The  release  is  the  portion  of  a  note  as  it  dies  away.  Long  releases  can  produce  a  nice 
ringing  quality,  but  can  also  be  a  problem  if  a  note  is  still  sounding  when  another  note 
starts  and  is  dissonant  with  the  first  note, 
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Note  Synthesizer  envelopes 

The  envelope  definition  in  the  Note  Synthesizer's  instrument  record  is  somewhat  more 
complex  than  this  simple  four-part  scheme.  The  instrument's  envelope  field  can  specify  up 
to  eight  segments  instead  of  just  four,  so  more  complex  sequences  of  attack,  decay, 
sustain,  and  release  are  possible.  For  example,  the  physical  properties  of  pianos  cause 
them  to  have  a  complex  envelope  with  two  attack  segments.  A  simple  ADSR  is  therefore 
limited  in  its  ability  to  simulate  a  piano's  envelope.  The  Note  Synthesizer  can  do  better, 
because  its  eight  envelope  segments  allow  a  closer  approximation  of  the  piano's  actual 
envelope. 

Figure  41-2  shows  an  envelope  created  with  eight  envelope  segments. 


■   Figure  41-2     Typical  Note  Synthesizer  envelope 
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An  instrument's  envelope  definition  is  composed  of  up  to  eight  linear  segments.  During 
each  segment,  the  note's  loudness  slopes  from  its  starting  value  toward  its  defined 
breakpoint  value.  The  segments  are  defined  as  a  series  of  breakpoints  and  increments. 

The  breakpoint  respresents  the  loudness  of  the  sound  in  a  byte  value  between  0  and  127 
on  a  logarithmic  loudness  scale.  A  value  difference  of  l6  represents  a  change  of  6  decibels 
in  loudness. 
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The  increment  determines  the  amount  of  time  to  be  spent  reaching  the  brealcpoint 
volume.  The  value  is  a  2-byte  fixed-point  number  which  indicates  the  amount  by  which  the 
current  volume  is  to  be  adjusted  at  each  update  (the  default  rate  is  100  updates  per 
second;  you  can  set  other  values  with  the  Nsstartup  and  NSSetupdateRate  tool 
calls).  The  low-order  byte  contains  the  numerator  for  a  fractional  increment.  For  example, 
an  increment  value  of  1  translates  to  a  fractional  increment  of  !^56.  In  this  case,  the  volume 
will  be  incremented  once  every  256  interrupts.  The  Note  Synthesizer  will  process  the 
segment  until  its  volume  reaches  the  specified  breakpoint  value,  at  which  time  it  moves 
to  the  next  segment. 

The  shape  of  the  envelope  is  arbitrary;  it  can  be  any  shape  that  can  be  specified  in  eight 
segments,  so  complex  envelopes  are  possible.  The  last  breakpoint,  though,  should  always 
be  0,  so  that  the  note  dies  away  at  the  end.  The  volume  should  not  go  to  0  before  the  end 
of  the  segment  or  the  sound  is  considered  done. 

The  length  of  time  that  a  segment  of  the  envelope  lasts  is  given  by  the  following  formula: 

^  ia-N)l«256 
'  (0.4)*a»R) 


where 

T  =  segment's  duration 
L  "  last  breakpoint 
N  •=  next  breakpoint 
I  -=  increment  value 
R  =  update  rate' 

As  an  example,  for  a  segment  that  changes  from  30  to  40  with  an  increment  value  of  25  and 
an  update  rate  of  100  cycles  per  second,  the  formula  becomes 

.      I60^0)h256  _    2560  _ 


(0.4)»(25»100)  (0.4)2500 


Thus,  with  the  given  parameters,  the  specified  segment  will  last  2.56  seconds. 
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The  increment  value  of  a  sustain  segment  is  0,  so  the  previous  formula  cannot  be  used  to 
calculate  the  duration  of  the  sustain  portion  of  an  envelope.  Instead,  the  sustain  portion 
simply  continues  until  a  release  is  signaled.  If  the  release  portion  of  the  note  sustains,  then 
the  note  will  continue  to  be  played  until  there  are  no  available  generators  left,  and  the 
generator  producing  the  note  is  reallocated  to  another  note. 


Instruments 

The  Note  Synthesizer's  basic  functional  unit  is  an  instrument  This  is  a  data  structure 
stored  somewhere  in  the  memory  of  the  Apple  IIGS  that  defines  the  sound  characteristics 
of  a  played  note.  When  a  program  makes  the  Noteon  call,  it  passes  a  pointer  to  an 
instrument,  and  that  instrument  is  used  while  generating  the  sound.  Figure  41-3  shows  the 
format  of  the  instrument  data  structure. 


■   Figure  41-3     Instrument  data  structure 


envelope 

24  Bytes 

$18 

releaseSegment 

Byte 

$19 

priority Increment 

Byte 

$1A 

pitchbendRange 

Byte 

$1B 

VibratoDepth 

Byte 

$1C 

vibratoSpeed 

Byte 

$1D 

Spare 

Byte 

$1E 

aWaveCount 

Byte 

$1F 

bWaveCount 

Byte 

$20 

aWaveList         •'  aWaveCount  Wavc  entries 


$xx 

:         bWaveList         :  bWaveCount  Wave  entries 

i  _J 
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envelope         Specifies  the  envelope  for  the  sound,  as  a  series  of  8  segments,  each  a 
breakpoint  and  increment  value  pair  (see  "Note  Synthesizer 
envelopes"  in  this  chapter  for  detailed  information  on  these 
concepts).  Each  breakpoint  is  a  one-byte  value  specifying  a  target 
volume  level  in  the  range  from  0  through  127.  Each  increment  is  a 
two-byte  value  which  determines  the  amount  of  time  the  Note 
Synthesizer  will  spend  reaching  the  breakpoint  volume. 

The  envelope  array  has  the  following  format; 


breakpolntO 

incrementO 

breakpointl 

incrementl 

Byte-^reakpoint  value  for  segment  0 
Word— Inaement  value  for  segment  0 
Byte— Breakpoint  value  for  segment  1 
Word— Inaement  value  for  segment  1 


breakpoint 7 

increment7 

Byte— Breakpoint  value  for  segment  7 
Word— Inaement  value  for  segment  7 


releaseSegment 

Defines  the  segment  at  which  release  begins  when  a  NoteOf  f  call  is 
made.  Its  value  can  be  any  number  from  0  to  7,  and  identifies  which 
segment  in  sequence  is  the  beginning  of  the  release  phase  of  the 
envelope.  The  release  portion  may  thus  occupy  several  segments,  but 
the  last  breakpoint  should  always  be  0.  For  example,  if 
releaseSegment  is  set  to  5  and  breakpoint?  has  a  value  of  0,  the 
Note  Synthesizer  ramps  through  segments  5,  6,  and  7  before  shutting 
down. 
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prioritylncrement 

Subtracted  from  the  generator's  priority  value  when  the  envelope 
reaches  its  sustain  phase.  The  Note  Synthesizer  uses  the  changing 
priority  values  to  reallocate  generators,  giving  higher  priority  to  notes 
that  are  just  starting.  When  an  envelope  reaches  the  release  portion, 
the  priority  value  assigned  to  its  generator  is  again  reduced,  this  time 
to  half  its  current  value.  Thus,  the  higher  priorities  go  to  notes  that  are 
just  starting;  notes  being  sustained  are  accorded  lower  priority,  and 
notes  in  their  release  phase  receive  lowest  priority.  This  is  just  a  rule  of 
thumb;  the  actual  priority  values  depend  on  the  priority  that  was 
specified  when  the  generator  was  allocated.  For  more  information  on 
generator  priorities,  see  "Generators"  in  this  chapter. 

pitchbendRange 

Specifies  the  maximum  pitch  bend  that  is  possible  on  the  note.  The 
maximum  possible  value  for  a  pitch  bend  is  127;  pitchbendRange 
specifies  by  how  many  semitones  the  pitch  is  raised  with  the  pitch 
bend  value  of  127.  The  legal  values  are  1, 2,  and  4  semitones.  Note  that 
the  only  way  to  change  the  pitchbend  value  for  a  note  that  is  playing  is 
to  change  the  pitchbend  field  of  the  appropriate  Generator  Control 
Block  (GCB)  (see  "Generators"  in  this  chapter  for  information  on  the 
format  and  content  of  the  GCB). 

The  pitchbend  field  is  mainly  used  by  the  Note  Sequencer.  It  is 
possible  to  set  its  value  directly,  but  it  is  normally  used  by  the  Note 
Sequencer  to  pass  information  to  the  Note  Synthesizer  about  how  to 
play  notes  in  a  sequence. 

vibratoDepth   Any  number  from  0  to  127.  A  depth  of  0  specifies  that  there  is  no 
vibrato  effect  on  the  note.  Vibrato  is  produced  by  modulating  the 
pitch  of  the  two  oscillators  that  make  up  a  generator,  using  a  triangle 
wave  produced  by  a  Low  Frequency  Oscillator  (LFO).  When  the 
vibratoDepth  parameter  specifies  that  there  is  to  be  no  vibrato 
effect,  the  vibrato  software  is  switched  off  to  save  processing  time, 
because  the  processing  required  to  create  the  triangle  wave  can 
consume  a  large  amount  of  processor  time. 

vibratospeed   Controls  the  rate  of  vibrato.  Higher  values  produce  faster  vibrato.  The 
actual  speed  of  vibrato  effect  depends  on  the  update  rate,  which 
defaults  to  100  updates  per  second,  You  can  set  other  rates  with  the 
NSStartUp  and  NSSetUpdateRate  tOOl  calls. 
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aWaveCount,  bWaveCount 

Specify  the  number  of  waves  in  the  wavelists  that  follow  the 
wavecounts.  The  Note  Synthesizer  can  use  sampled  or  artificially 
created  waveforms  to  produce  its  notes. 

aWaveList,  bWaveList 

A  wavelist  is  an  array  of  variable  length.  The  elements  of  the  array  are 
6-byte  structures  A  wavelist  can  contain  up  to  255  entries. 

An  entry  in  a  wavelist  data  structure  specifies  wave  data  that  is 
intelligible  for  the  DOC.  The  Note  Synthesizer  places  the  data  into  the 
DOC  registers. 


$00 

topKey 

Byte 

$01 

waveAddress 

Byte 

$02 

waveSize 

Byte 

$03 

DOCMode 

Byte 

$04 

—          relPltch  — 

Word 

topKey 


waveAddress 


waveSize 


When  the  Note  Synthesizer  plays  a  note,  it  examines  the  topkey 
field  of  each  waveform  in  the  wavelists  until  it  finds  a  value  that 
is  greater  than  or  equal  to  the  value  of  the  note  it  is  attempting 
to  play.  The  first  waveform  it  finds  with  an  acceptable  topkey 
value  is  the  one  it  plays.  For  this  reason,  waveforms  should  be 
stored  in  increasing  order  of  topkey  value.  The  last  waveform  in 
a  wavelist  should  have  a  value  of  127,  the  maximum  valid  pitch 
value. 

The  waveAddress  parameter  is  the  high  byte  of  the  waveform's 
address  in  Sound  RAM.  Its  value  is  copied  into  the  Address 
Pointer  register  of  the  DOC. 

The  waveSize  parameter  sets  the  size  of  the  DOC's  wave  table, 
and  the  frequency  resolution  of  the  DOC.  This  parameter  is 
copied  directly  to  the  DOC's  Bank-Select/TableSize/Resolution 
register.  The  resolution  and  table  size  should  normally  be  equal. 
See  Chapter  47,  "Sound  Tool  Set  Update,"  in  this  book  and  the 
Apple  IlGS  Hardware  Reference  for  more  information. 
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DOCMode  The  DOCMode  parameter  sets  the  mode  of  the  Digital  Oscillator 

Chip.  This  parameter  corresponds  to  the  Control  register  of  the 
DOC,  and  supplies  the  stereo  position  of  the  oscillator.  Bit  3  of 
this  register  (the  interrupt  enable  bit  for  the  DOC)  should  always 
be  set  to  0.  See  Chapter  47,  "Sound  Tool  Set  Update,"  in  this 
book  and  the  Apple  IIGS  Hardware  Reference  for  more 
information. 

reiPitch         The  reiPitch  parameter  is  a  word  value  that  is  used  to  tune  the 
waveform.  The  high-byte  value  is  the  semitone,  and  the  low  byte 
is  fractions  of  semitones.  A  value  of  1  in  the  low  byte 
corresponds  to  V'2«of  a  semitone.  A  wavelist  can  specify  a  full 
range  of  notes  for  an  instrument  with  entries  for  each  note  that 
differ  only  in  the  reiPitch  field.  Such  a  wavelist  would  specify 
an  instrument  whose  timbre  is  the  same  for  every  note;  only  the 
pitch  is  different. 

For  more  information  on  DOC  registers  and  waveforms,  see 

Chapter  47,  "Sound  Tool  Set  Update,"  in  this  book  and  the  Apple  IIGS  Hardware  Reference. 


DOC  memory 

One  page  of  bank  zero  memory  must  be  allocated  to  the  Sound  Tool  Set  for  use  as  a 
direct  page.  The  Note  Synthesizer  shares  this  direct-page  space  with  the  Sound  Tool  Set. 

An  application  that  uses  the  Note  Synthesizer  must  load  any  waveforms  that  it  can  use 
into  DOC  memory  with  the  Sound  Tool  Set  call  writeRAMBiock.  You  must  not  place  a  0 
in  the  first  256  bytes  of  DOC  memory  because  it  halts  the  timer  oscillator;  this  will  cause  a 
system  failure.  If  the  application  uses  the  clock  function  of  the  MIDI  tools,  then  it  must 
not  write  to  the  first  256  bytes  of  DOC  memory. 


Generators 

Each  generator  is  a  pair  of  DOC  oscillators.  There  are  32  such  oscillators;  two  of  them  are 
reserved  for  the  use  of  Apple  Computer,  Inc.  The  remaining  30  are  paired  into  15 
generators  for  the  Note  Synthesizer.  The  Note  Synthesizer  uses  one  of  these  generators  as 
a  timer,  leaving  14  generators  for  general  use.  If  the  MIDI  Tool  Set  is  started  up  and  is 
using  the  MIDI  clock  function,  another  generator  is  allocated  to  serve  as  the  MIDI  clock, 
leaving  13  general-purpose  generators  for  application  use. 
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The  Note  Synthesizer  allocates  generators  to  all  the  different  sound  tools  that  may  need 
them.  It  therefore  requires  a  priority  scheme  for  allocating  generators  in  the  event  that  a 
generator  is  requested  when  all  generators  are  in  use.  When  a  generator  is  allocated,  it 
receives  a  priority.  A  generator's  priority  may  range  from  0  through  128.  A  priority  of  0 
means  the  generator  is  not  being  used  and  will  be  allocated  to  any  use  that  requests  it.  A 
priority  of  128  indicates  that  the  generator  is  locked  and  cannot  be  reallocated.  The 
remaining  values  in  a  generator's  range  are  used  by  the  Note  Synthesizer  to  control 
allocation  of  generators. 

The  Note  Synthesizer  automatically  lowers  the  priority  of  a  generator  that  has  reached  the 
sustain  portion  of  its  envelope,  and  lowers  it  again  when  it  reaches  the  release  portion. 
When  the  note  stops,  the  generator's  priority  becomes  0.  An  application  specifies  a 
priority  when  requesting  allocation  of  a  generator,  so  that  allocation  occurs  when  a 
generator  is  available  with  a  priority  lower  than  that  requested. 

The  Note  Synthesizer  divides  its  direct-page  area  into  15  blocks  of  l6  bytes,  called 
generator  control  blocks  (GCB).  The  GCB  contains  the  values  of  any  "knobs"  or 
"controllers"  affecting  the  parameters  of  the  note  that  it  is  currently  playing.  A 
programmer  normally  should  not  access  the  GCB. 

Figure  41-4  shows  the  format  and  content  of  the  GCB. 
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■   Figure  4l4     Generator  control  block 


$00 

synthID 

$01 

genNum 

$02 

semitone 

$03 

volume 

$04 

pitchbend 

$05 

vibratoDepth 

$06 

Reserved  ■ 

Byte— Identifies  user  of  generator 

Byte— Identifies  the  generator  itself 

Byte— Note  currently  being  played  by  the  generator 

Byte— Output  volume  for  current  note 

Byte— Pitchbend  value  for  current  note 

Byte— Vibrato  for  current  note 

10  Bytes— Note  Synthesizer  and  Sound  Tools  reserved 


synthID 


Identifies  who  is  currently  using  the  generator.  Valid  values  are 


0  Not  used 

1  Sound  Tool  Set  freeform  synthesizer 

2  Note  Synthesizer 

3  Reserved  for  use  by  Apple  Computer,  Inc. 

4  MIDI  Tool  Set 

5-7  Reserved  for  use  by  Apple  Computer,  Inc. 

8-15  User  defined 

genNiim  Uniquely  identifies  the  generator.  Valid  values  lie  in  the  range  from  0 

through  13  ($00  through  $0D).  Your  application  uses  this  value  to 
identify  a  specific  generator  to  the  Note  Synthesizer.  The  tool  set 
returns  the  identifier  on  the  AiiocGen  call. 

Identifies  the  note  currently  being  played.  Contains  a  standard  MIDI 
value  in  the  range  from  0  to  127,  where  middle  C  has  a  value  of  60. 

Identifies  the  output  volume  for  the  current  note  specified  by 
semitone.  Valid  values  lie  in  the  range  from  0  through  127,  and 
correspond  to  MIDI  velocity.  A  l6-step  change  in  volume 
corresponds  to  a  6  decibel  change  in  amplitude. 

pitchbend        Identifies  pitch  bend  to  be  applied  to  the  note  specified  by 

semitone.  Valid  values  lie  in  the  range  from  0  through  127;  a  value  of 
64  specifies  no  pitch  bend.  The  pitchbendRange  field  of  the 
instrument  record  (see  "Instruments"  earlier  in  this  chapter)  specifies 
the  maximum  allowable  pitch  bend,  in  semitones. 


semitone 


volume 
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vibratoDepth    Specifies  the  depth  of  vibrato  for  the  note.  Valid  values  lie  in  the 

range  from  0  through  127.  A  value  of  0  indicates  no  vibrato  (this  is  the 
recommended  value).  A  value  of  127  yields  maximum  vibrato  depth. 

Reserved  Area  reserved  for  internal  use  by  the  Note  Synthesizer  and  the  Sound 

Tool  Set. 
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Note  Synthesizer  housekeeping  calls 

All  the  call  descriptions  for  the  Note  Synthesizer  are  new.  The  tool  calls  were  not  previously 
documented  in  the  Apple  IIGS  Toolbox  Reference. 

NSBootlnit  $0119 

Initializes  the  Note  Synthesizer. 

▲  Warning     An  application  must  not  make  this  call.  ▲ 

Parameters        This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  None 

C  extern  pascal  void  NSBootlnit () ; 
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NSStartUp  $0219 

Starts  up  the  Note  Synthesizer  for  use  by  an  application.  An  application  must  make  this 
call  before  it  makes  any  other  Note  Synthesizer  calls  except  Nsstatus  orNSVersion. 
The  updateRate  parameter  specifies  the  rate  at  which  interrupts  are  generated  to  update 
envelopes  and  low-frequency  oscillations.  The  value  is  in  units  of  0.4  Hz.  Reasonable 
values  for  this  parameter  include  150,  250,  and  500.  The  default  value  is  500.  Low  rates 
require  less  overhead,  but  higher  rates  generate  smoother  sounding  envelopes. 

The  userUpdateRtn  parameter  is  a  pointer  to  a  routine  that  is  called  during  every  timer 
interrupt.  Sequencer  programs  are  an  example  of  software  that  might  use  routines  that  run 
during  Note  Synthesizer  interrupts,  and,  in  fact,  this  is  how  the  Note  Sequencer  works.  A 
value  of  0  indicates  that  there  is  no  user  update  routine. 

Parameters 

Stack  before  call 


Previous  contents 


UpdateRate 


-  userUpdateRtn 


Word— Rate  of  envelope  generation 
Long— Pointer  to  custom  interrupt  routine 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1901 

$1902 
$1925 


<— SP 
nsAlreadylnit 

nsSndNotlnit 
soundWrongVer 


Note  Synthesizer  already  started 
up. 

Sound  Tool  Set  not  started  up. 
Incompatible  version  of  Sound 
Tool  Set. 


extern  pascal  void  NSStartUp (updateRate, 
userUpdateRtn) ; 


Word 
Pointer 


updateRate; 
userUpdateRtn; 
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NSShutDown  $0319 

Shuts  down  the  Note  Synthesizer  and  turns  off  all  generators.  An  application  should  make 
this  call  before  quitting. 

Parameters        This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  $1923      nsNotmit  Note  Synthesizer  not  started  up. 

C  extern  pascal  void  NSShutDown () ; 
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NSVersion  $04l9 

Returns  the  version  number  of  the  Note  Synthesizer.  Refer  to  Appendix  A,  "Writing  Your 
Own  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference  for  information  about  the  format  and 
content  of  the  versionNum  return  value. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


versionNum 


Word— Note  Synthesizer  version  number 


<— SP 


Errors 


None 


C 


extern  pascal  Word  NSVersion () ; 
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NSReset  $0519 

Resets  the  Note  Synthesizer. 

A  Warning     An  application  must  not  malce  this  call,  a 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  None 

C  extern  pascal  void  NSReset (); 


41-18    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  lIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


NSStatus  $0619 

Returns  a  Boolean  value  indicating  whether  the  Note  Synthesizer  is  active.  If  the  Note 
Synthesizer  is  active,  ns  status  returns  TRUE.  Otherwise,  the  call  returns  FALSE. 

♦  Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  NSStatus,  your  program  need  only  check  the 
value  of  the  returned  flag.  If  the  Note  Synthesizer  is  not  active,  the  returned  value  will 
be  FALSE  (NIL). 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


startStatus 


Word— Boolean;  TRUE  if  the  Note  Synthesizer  is  started 


<— SP 


Errors 


None 


C 


extern  pascal  Boolean  NSStatus (); 
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Note  Synthesizer  calls 

The  following  sections  discuss  the  Note  Synthesizer  tool  calls. 


AllNotesOff  $0D19 

Turns  off  all  Note  Synthesizer  generators  and  sets  their  priorities  to  0,  It  does  not  affect 
generators  not  used  by  the  Note  Synthesizer,  such  as  those  allocated  to  the  freeform 
synthesizer. 

Parameters  This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 
Errors  None 

C  extern  pascal  void  AllNotesOff {) ; 
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AllocGen  $0919 

Requests  the  allocation  of  a  sound  generator.  Returns  a  generator  number  from  0  to  13. 
The  call  will  reallocate  a  generator  if  all  generators  are  allocated  and  the  specified 
requestPriority  exceeds  that  of  one  of  the  previously  allocated  generators. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


requestPriority 


Stack  after  call 


Word— Space  for  result 
Word— Desired  generator  priority 
<— SP 


Previous  contents 


genNum 


Errors 


Word— Number  of  allocated  generator 
<— SP 


No  generators  available  to 
allocate. 

Note  Synthesizer  not  started  up. 


$1921  nsNotAvail 

$1923  nsNotlnit 
extern  pascal  Word  AllocGen (requestPriority) ; 

Word  requestPriority; 
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DeAllocGen  $0A19 

Sets  the  named  generator's  allocation  priority  to  zero  and  halts  its  oscillators.  Any 
subsequent  allocation  request  with  a  valid  requeslPriority'<N'A\  then  succeed. 

Parameters 

Stack  before  call 


Previous  contents 


genNum 


Stack  after  call 


Word— Number  of  generator  to  deallocate 
<— SP 


Previous  contents 


Errors 
C 


<— SP 

$1922      nsBadGenNum  Invalid  generator  number, 

extern  pascal  void  DeAllocGen (genNum) ; 
Word  genNum; 
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NoteOff  $0C19 


Switches  the  specified  generator  to  release  mode,  which  causes  the  note  being  generated 
to  die  out.  When  the  note's  volume  is  0,  the  generator's  priority  is  set  to  0,  and  it  is 
considered  to  be  off.  The  genNum  and  semitone  parameters  should  be  set  to  the  same 
values  specified  in  the  corresponding  NoteOn  call. 

Parameters 

Stack  before  call 


Previous  contents 


genNum 


semitone 


Stack  after  call 


Word— Generator  number 
Word— Note  being  played 
<— SP 


Pretnous  contents 


Errors 
C 


<— SP 
None 

extern  pascal  void  NoteOff (genNum,  semitone) 
Word  genNum,  semitone; 
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NoteOn  $0B19 


Initiates  the  generation  of  a  note  on  a  specified  generator.  The  genNum  parameter  should 
be  a  value  returned  by  the  AiiocGen  call.  The  semitone  parameter  is  a  standard  MIDI 
value  from  0  to  127,  where  middle  C  is  designated  by  the  value  60.  The  volume  parameter 
is  a  value  from  0  to  127  that  can  be  treated  as  synonymous  with  MIDI  velocity.  The  value  is 
copied  into  the  generator  control  block,  and  is  used  to  sale  the  note's  amplitude.  A 
change  of  l6  steps  in  this  parameter  specifies  a  change  of  6  decibels  in  amplitude.  The 
instrumentPtr  parameter  is  a  pointer  to  an  instrument.  See  "Instmments"  earlier  in  this 
chapter  for  more  information  on  the  instrument  data  structure. 


♦  Note:  Experiment  with  the  volume  parameter  and  envelope  amplitudes;  if  the  sum  of 
these  two  values  is  too  small,  the  note  being  played  will  be  inaudible  even  if  everything 
else  is  working  correctly.  The  dynamic  range  of  the  DOC  is  48  decibels. 


Parameters 

Stack  before  call 


Previous  contents 


genNum 


semitone 


volume 


-  instrumentPtr  - 


Word— Generator  number 
Word— Desired  pitch  for  note 
Word— Desired  volume  for  note 

Long— Pointer  to  instrument  to  play  note 

<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

$1924  nsGenAlreadyOn 


The  specified  note  is  already 
being  played. 
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extern  pascal  void  NoteOn (genNum,   semitone,  volume, 
instrumentPtr)  ; 


Word  genNum,   semitone,  volume; 

Pointer  instrumentPtr; 

Example 

The  following  example  shows  assembly-language  code  that  allocates  a  generator,  passes 
the  correct  parameters  to  NoteOn,  plays  a  note,  and  turns  off  the  note. 


pushword  #0 
pushword  #64 
_AllocGen 
pla 

sta  GenNum 


; space  for  GenNum 

; priority  of  this  note 

; retrieve  an  allocated  generator 

;get  the  generator  number 

; store  it 


definition 


pushword  GenNum 
pushword  Semitone 
pushword  #127 
pushlong  #Instrument 

NoteOn 


After  some  time.. 


pushword  GenNum 
pushword  Semitone 
NoteOf f 


;push  parameters : generator 
;  note 

;  maximum  volume 

;LONG  pointer  to  instrument 


;push  parameters:  generator 
;  note 

;turn  off  the  note 
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NSSetUpdateRate  $0E19 

Sets  the  Note  Synthesizer's  updateRate  parameter,  as  described  in  the  Nsstartup 
section.  The  specified  updateRate  value  becomes  the  new  updateRate,  and  the  old  value  is 
returned. 

Parameters 

Stack  before  call 

Previous  contents 


UpdateRate 


Space 


Word— Space  for  result 
Word— New  update  rate 


<— SP 


Stack  after  call 


Previous  contents 


oldRate 


Word— Update  rate  before  call 


<— SP 


Errors 


$1923 


nsNotlnit 


Note  Synthesizer  not  started  up. 


C 


extern  pascal  Word  NSSetUpdateRate (updateRate)  ; 


Word 


updateRate; 


41-26    Apple  IIGS  Toolbox  Reference,  Volume  3 


/^ple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


NSSetUserUpdateRtn  $0F19 

Sets  the  user  update  routine  described  in  tiie  Nsstartup  section.  Tlie  update  routine 
pointer  is  set  to  the  value  passed  in  the  userUpdateRtn  parameter,  and  the  address  of  the 
old  update  routine  is  returned.  If  there  is  no  user  update  routine  when  this  call  is  made,  it 
returns  a  NULL  pointer.  A  NULL  userUpdateRtn  value  disables  the  current  update  routine. 

Parameters 

Stack  before  call 


Pretnous  contents 


Space 


-  userUpdateRtn  - 


Long— Space  for  result 

Long— Pointer  to  new  update  routine 
<— SP 


Stack  after  call 


Pretnous  contents 


oldRtn 


Errors 
C 


$1923 


Long— Pointer  to  old  update  routine 
<— SP 

nsNotinit  Note  Synthesizer  not  started  up. 


extern  pascal  VoidProcPtr 

NSSetUserUpdateRtn (userUpdateRtn) ; 


Pointer  userUpdateRtn; 
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Note  Synthesizer  error  codes 

This  section  lists  the  error  codes  that  may  be  returned  by  Note  Synthesizer  calls. 


Value  Name  Definition 


$1901 

nsAlreadylnit 

Note  Synthesizer  already  started  up. 

$1902 

nsSndNotlnit 

Sound  Tool  Set  not  started  up. 

$1921 

nsNotAvail 

No  generators  available  to  allocate. 

$1922 

nsBadGenNum 

Invalid  generator  number. 

$1923 

nsNotlnit 

Note  Synthesizer  not  started  up. 

$1924 

nsGenAlreadyOn 

The  specified  note  is  already  being  played. 

$1925 

soundWrongVer 

Incompatible  version  of  Sound  Tool  Set. 
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Chapter  42  Print  Manager  Update 


This  chapter  documents  new  features  of  the  Print  Manager.  The  complete 
reference  to  the  Print  Manager  is  in  Volume  1,  Chapter  15  of  the 
Apple  UGS  Toolbox  Reference. 
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Error  corrections 

This  section  documents  errors  in  the  Toolbox  Reference. 

m  The  diagram  for  the  job  subrecord,  figure  15-10  on  page  15-14  of  the  Toolbox  Reference, 
shows  that  the  f  Fromusr  field  is  a  word.  This  is  incorrect.  The  f  Fromusr  field  is 
actually  a  byte.  Note  that  the  offsets  for  all  fields  following  this  one  are  incorrect,  as  a 
result.  This  error  is  also  reflected  in  the  tool  set  summary  at  the  end  of  the  chapter. 

■  The  description  of  the  Pr  jobDiaiog  tool  call  states  that  "The  initial  settings 

displayed  in  the  dialog  box  are  taken  from  the  printer  driver . . .."  This  is  incorrect.  The 
sentence  should  begin  "The  initial  settings  displayed  in  the  dialog  box  are  taken  from 
the  print  record . . .." 


Clarifications 

■  The  existing  Toolbox  Reference  documentation  for  the  PrPicFiie  tool  call  does  not 
mention  that  your  program  may  pass  a  NIL  value  for  statusRecPtr.  Passing  a  NIL  pointer 
causes  the  system  to  allocate  and  manage  the  status  record  internally. 

■  The  PrPixeiMap  call  (documented  in  Volume  1  of  the  Toolbox  Reference)  provides  an 
easy  way  to  print  a  bitmap.  It  does  much  of  the  required  processing,  and  an 
application  need  not  make  the  calls  normally  required  to  start  and  end  the  print  loop. 
The  5rciocF/r  parameter  must  be  a  pointer  to  a  loclnfo  record  (see  Figure  l6-3  in 
Chapter  l6,  "QuickDraw  II,"  in  the  Toolbox  Reference  for  the  layout  of  the  loclnfo 
record). 
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New  features  in  the  Print  Manager 

The  following  functions  have  been  added  to  the  Print  Manager: 

■  The  port  driver  auxiliary  file  type  of  an  AppleTalk  driver  is  $0003.  Its  file  type  remains 
$BB. 

■  The  PRINTER.SETUP  file  now  saves  separate  settings  for  direct  and  network 
connections  to  printers.  Old  versions  of  the  PRINTER.SETUP  file  are  incompatible 
with  these  changes,  so  the  Print  Manager  will  delete  such  files  and  create  a  new  one  in 
the  correct  format.  Old  settings  are  discarded,  and  the  default  settings  are  used  to 
create  the  new  setup  file. 

■  If  the  Print  Manager  attempts  to  load  a  driver  and  finds  that  it  is  missing,  it  will  pass 
control  to  a  routine  that  determines  what  call  was  being  made  to  the  driver,  pops  the 
parameters  off  the  stack,  and  returns  a  missingDriver  error  ($1301).  It  will  also 
display  an  alert  asking  the  user  to  make  sure  a  printer  and  port  driver  are  selected,  if 
Pr  jobDiaiog  and  PrStiDialog  are  called. 

■  The  PMStartup  call  does  not  load  any  drivers  into  memory.  Drivers  are  loaded  only 
when  they  are  needed.  The  Print  Manager  does  not  require  that  the  DRIVERS  folder  be 
present,  and  if  it  is  present,  does  not  require  that  there  be  any  drivers  in  it. 

■  The  PrChoosePrinter  call  is  no  longer  supported.  Users  should  now  use  the  Control 
Panel  desk  accessory  to  choose  new  printers.  When  an  application  issues  the 
prChoosePrinter  call,  the  Print  Manager  will  display  an  alert  directing  the  user  to 
use  the  Control  Panel.  New  applications  should  never  issue  this  call  and  should  not 
include  the  Choose  Printer  item  in  the  file  menu.  Note  that  PMStartup  will  still  load 
the  List  Manager  if  it  has  not  already  been  loaded. 

■  Print  Manager  now  allows  you  to  assign  a  name  to  a  document.  This  feature  is  primarily 
applicable  to  documents  destined  for  AppleTalk  printers. 

■  Currently,  if  a  user  wants  to  print  multiple  copies  of  a  document  in  draft  mode  to  an 
Image  Writer®,  Image  Writer  LQ,  or  Epson  printer,  your  application  must  run  through 
its  print  loop  once  for  each  copy.  The  draft  mode  flag  and  copy  count  fields  are 
located  in  the  Job  subrecord  of  the  print  record. 

■  The  LaserWriter  driver  will  now  use  some  PostScript®  fonts  diat  have  been 
downloaded  into  the  printer  by  another  computer. 
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New  Print  Manager  calls 

The  following  sections  discuss  new  Print  Manager  tool  calls. 


PMLoadDriver  $3513 

Loads  the  current  printer  driver,  port  driver,  or  both,  depending  on  the  input  parameter. 
The  current  driver  is  determined  by  the  settings  saved  in  the  PRINTER.SETUP  file. 

Parameters 

Stack  before  call 


Previous  contents 


whichDriver 


Stack  after  call 


Word— Printer  driver  to  load 
<— SP 


Previous  contents 


Errors 


$1309 


<— SP 
badParam 


The  specified  parameter  is 
invalid. 


C  extern  pascal  void  PMLoadDriver (whichDriver) ; 

Word  whichDriver; 

whichDriver       Specifies  which  printer  driver  to  load.  Legal  values  for  the  driver 
parameter  include 

0  Load  both  drivers. 

1  Load  printer  driver. 

2  Load  port  driver. 
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PMUnloadDriver  $3413 

Unloads  the  current  port  driver,  printer  driver,  or  both,  depending  on  the  input  parameter. 

Parameters 

Stack  before  call 


Previous  contents 


whichDriver 


Stack  after  call 


Word— Printer  driver  to  unload 
<— SP 


Previous  contents 


Errors 


$1309 


<— SP 
badParam 


The  specified  parameter  is 
invalid. 


C  extern  pascal  void  PMUnloadDriver (whichDriver) ; 

Word  whichDriver; 

whichDriver       Specifies  which  printer  driver  to  unload.  Legal  values  for  the  driver 
parameter  include 

0  Unload  both  drivers. 

1  Unload  printer  driver. 

2  Unload  port  driver. 
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PrGetDocName  $36l3 

Returns  a  pointer  to  the  current  document  name  string  for  your  document.  Use  the 
PrSetDocName  tool  Call  to  set  or  change  the  document  name. 

Note  that  there  is  only  one  active  document  name  for  the  system  at  any  given  time.  Your 
application  must  correctly  manage  this  name  in  the  context  of  the  document  being 
printed. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


-  docNamePtr 


Long— Pointer  to  document  name  string  (Pascal  string) 


<— SP 


Errors 


None 


C 


extern  pascal  Pointer  PrGetDocName () ; 
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PrGetPgOrientation  $3813 

Returns  a  value  indicating  the  current  page  orientation  for  the  specified  document. 

Parameters 

Stack  before  call 

Previous  contents 


-  prRecordHandle  - 


Space 


Word— Space  for  result 

Long— Handle  to  print  record  for  document 


<— SP 


Stack  after  call 


Previous  contents 


orientation 


Word— Page  orientation:  O=portrait,  l=landscape 


<— SP 


Errors 


None 


C 


extern 


pascal  Word 

PrGetPgOrientation (prRecordHandle)  ; 


Handle 


prRecordHandle; 
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PrGetPrinterSpecs  $1813 

Returns  information  about  the  currently  selected  printer. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Space 


Stack  after  call 


Word— Space  for  result 
Word— Space  for  result 
<— SP 


Previous  contents 


characteristics 


printerType 


Errors 


None 


Word— Word  defining  printer  characteristics 
Word— Word  indicating  the  type  of  printer  connected 
<— SP 


C  extern  pascal  PrinterSpecs  PrGetPgOrientation () ; 

characteristics      Defines  the  features  of  the  particular  printer: 

Reserved  bits  2-15    Must  be  set  to  0 

color  bits  0-1     Indicates  color  capability: 

00  -  Can't  determine 

01  -  Black  and  white  only 
10 -Color 

11  -  Invalid  value 

printerType         Indicates  the  type  of  printer  selected: 

0  undefined 

1  Image  Writer  I  or  II 

2  Image  Writer  LQ 

3  LaserWriter®  family  (LaserWriter,  Plus,  and  11) 

4  Epson 
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PrSetDocName  $3713 


Sets  the  document  name  for  use  with  AppleTalk  printers.  Print  Manager  passes  this  name 
when  connecting  to  printers  and  spoolers,  so  that  the  destination  printer  may  properly 
report  the  name. 

Note  that  there  is  only  one  active  document  name  for  the  system  at  any  given  time.  Your 
application  must  correctly  manage  this  name  in  the  context  of  the  document  being 
printed. 

In  some  status  windows,  the  document  name  may  be  truncated.  To  avoid  name 
truncation,  you  should  use  names  containing  fewer  than  32  characters. 

Parameters 

Stack  before  call 


Previous  contents 


-   docNamePtr  - 


Long— Pointer  to  document  name  string  (Pascal  string) 
<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


None 


extern  pascal  void  PrSetDocName (docNamePtr) ; 
Pointer  docNamePtr; 
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Previously  undocumented  Print  Manager  calls 

The  following  calls  have  not  previously  been  documented,  but  may  be  useful  to 
application  programmers. 


PrGetNetworkName  $2B13 

Retums  the  AppleTalk  network  name  for  the  currently  selected  printer.  If  the  user  has 
selected  a  non-networked  printer,  the  call  returns  a  ML  pointer. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


-    netNamePtr  - 


Long— Pointer  to  printer  network  name  string  (Pascal  string) 


<— SP 


Errors 


None 


C 


extern  pascal  Pointer  PrGetNetworkName () ; 
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PrGetPortDvrName  $2913 

Returns  the  name  string  for  the  currently  selected  port  driver. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long — Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


-  prtDvrNamePtr 


Lon^Pointer  to  port  driver  name  string  (Pascal  string) 


<— SP 


Errors 


None 


C 


extern  pa 


seal  Pointer  PrGetPortDvrName () ; 
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PrGetPrinterDvrName  $2813 

Returns  the  name  string  for  the  currently  selected  printer  driver. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


-  prtDvrNamePtr 


Long— Pointer  to  printer  driver  name  string  (Pascal  string) 


<— SP 


Errors 


None 


C 


extern  pascal  Pointer  PrGetPrinterDvrName {) ; 
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PrGetUserName  $2A13 

Returns  the  user  name  as  entered  in  the  Control  Panel. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


-  userNamePtr  - 


Long— Pointer  to  user  name  string  (Pascal  string) 


<— SP 


Errors 


None 


C 


extern 


pascal  Pointer  PrGetUserName () ; 
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PrGetZoneName  $2513 

Returns  the  name  string  for  the  currently  selected  AppleTalk  print  zone.  If  the  user  has 
selected  a  non-networked  printer,  then  the  call  returns  a  NIL  pointer. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


-  zoneNamePtr  - 


Long— Pointer  to  zone  name  string  (Pascal  string) 


<— SP 


Errors 


None 


C 


extern  pascal  Pointer  PrGetZoneName () ; 
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Print  Manager  error  codes 


This  section  lists  all  valid  Print  Manager  error  codes. 


Value 

Name  Definition 

$1301 

mi  ssingD river 

Specified  driver  not  in  the  DRIVERS 

subdirectory  of  the  SYSTEM  subdirectory. 

$1302 

portNotOn 

Specified  port  not  selected  in  the  control 

panel. 

$1303 

noPrintRecord 

No  print  record  specified 

$1306 

papConnNotOpen 

Connection  cannot  be  established  with  the 

LaserWriter. 

$1307 

papReadWriteErr 

Read-write  error  on  the  LaserWriter. 

$1308 

pntrConFailed 

Cannot  establish  connection  with  Image  Writer. 

$1309 

badParam 

Invalid  parameter  for  load  or  unload. 

$130A 

callNot Supported 

Tool  call  is  not  supported  by  current  version  of 

the  driver. 

$1321 

startUpAlreadyMade 

LLDStartup  call  already  made. 
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Chapter  43  QuickDraw  n  Update 


This  chapter  documents  new  features  of  QuickDraw™  11.  The  complete 
reference  to  QuickDraw  II  is  in  Volume  2,  Chapter  l6  of  the 
Apple  IlGS  Toolbox  Reference. 


43-1 


Apple  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Error  corrections 

The  following  items  provide  corrections  to  the  documentation  for  QuickDraw  II  in  the 
Apple  IIGS  Toolbox  Reference: 

m  The  documentation  in  the  Toolbox  Reference  that  explains  pen  modes  is  somewhat 
misleading.  There  are,  in  fact,  8  drawing  modes,  and  you  may  set  the  pen  to  draw  lines 
and  other  elements  of  graphics  in  any  of  these  modes.  There  are  also  16  modes  used  for 
drawing  text,  and  they  are  completely  independent  of  the  graphic  pen  modes.  The  8 
drawing  modes  listed  in  Table  16-9  on  page  16-235  are  valid  modes  for  either  the  text 
pen  or  the  graphics  pen.  You  can  set  either  pen  to  any  of  these  modes  by  using  the 
appropriate  calls.  You  can  also  set  the  text  pen  to  8  other  modes.  These  modes  are 
listed  in  the  table  on  page  16-260  of  the  Toolbox  Reference.  The  setPenMode  call  sets 
the  mode  used  by  the  graphics  pen;  the  SetTextMode  call  sets  the  mode  used  by  the 
text  pen.  Setting  either  one  does  not  affect  the  other. 

■  There  are  two  versions  of  the  Apple  IIGS  standard  640-mode  color  tables,  one  on  page 
16-36  and  one  on  page  16-159.  The  two  tables  are  different;  Table  16-7  on  page  16-159 
is  correct. 

■  In  the  QuickDraw  II  chapter,  the  Apple  IIGS  Toolbox  Reference  states  that  the 
coordinates  passed  to  the  LineTo  andMoveTo  calls  should  be  expressed  as  global 
coordinates.  In  fact,  the  coordinates  must  be  local  coordinates,  and  must  refer  to  the 
GrafPort  in  which  the  drawing  or  moving  takes  place. 
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New  features  in  QuickDraw  n 

The  following  information  describes  new  features  in  this  version  of  QuickDraw  II. 

■  QuickDraw  II  now  supports  16  bit  by  8  bit  pbcel  patterns  in  640  mode.  To  use  these 
larger  patterns,  set  the  high-order  bit  (bit  15)  of  the  arcRot  word  in  the  GrafPoit 
record  to  1.  QuickDraw  n  will  then  use  all  32  bytes  of  the  passed  pattern.  Since  the 
openPort  and  initPort  tool  calls  clear  this  bit,  existing  applications  will  work  fine. 

PointinRect  now  works  as  previously  documented. 

■  In  the  FONT  folder  on  your  system  disk  you  will  find  a  file  named  FASTFONT.  This  file 
contains  a  special  version  of  the  Shaston  8  font  that  will  provide  markedly  improved 
performance  for  text  drawing  under  many  circumstances.  Specifically,  this  font  can  be 
used  whenever  you  are  drawing  plain,  black  text  on  a  white  background  into  a 
rectangulariy  clipped  region.  While  this  may  sound  overiy  restrictive,  most  applications 
draw  text  in  precisely  this  way.  This  font  reduces  text  drawing  time  by  more  than  half. 

To  use  this  font,  QuickDraw  n  must  find  it  in  your  FONT  folder  when  the  tool  is 
started.  If  your  application  draws  text  to  an  off-screen  bitmap,  use  openPort  and 
InitPort  to  set  up  the  off-screen  buffers  in  order  to  insure  that  FASTFONT  is 
properly  installed. 


QuickDraw  n  speed  enhancement 

In  addition  to  FASTFONT,  QuickDraw  II  has  several  other  changes  that  improve  drawing 
performance.  First,  pattem  filling  in  modecopy  and  modexoR  now  operates  between  2 
and  4  times  faster.  The  remaining  changes  require  that  you  modify  your  application  to 
take  advantage  of  the  performance  improvements  they  offer. 

QuickDraw  II  now  supports  hardware  shadowing  of  screen  images.  This  feature  uses  32  KB 
of  bank  1  memory  to  store  the  screen  image.  By  storing  the  image  in  memory,  QuickDraw 
II  can  offer  an  8  to  20  percent  speed  improvement  in  all  operations.  You  control  whether 
QuickDraw  II  uses  the  shadow  memory  by  setting  a  flag  in  the  masterSCB  parameter 
passed  to  the  QDStartup  tool  call.  If  QuickDraw  II  cannot  allocate  the  needed  memory, 
it  will  reset  the  flag  and  operate  without  shadowing  in  effect.  Use  the  GetMasterSCB 
tool  call  to  read  the  masterSCB  back  and  check  shadow  status. 
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In  addition,  your  application  can  further  improve  QuiclcDraw  II  performance  by  following 
some  simple  rules.  First,  your  application  must  only  change  GrafPort  fields  via  QuickDraw 
n  tool  calls,  not  by  directly  accessing  the  record  fields.  Next,  for  best  results  perform 
similar  operations  in  groups.  For  example,  if  your  application  needs  to  erase  and  redraw 
four  rectangles,  it  should  do  all  the  erases  together,  then  all  the  draws.  In  this  manner, 
QuickDraw  II  only  has  to  change  its  drawing  pattem  twice,  rather  than  eight  times.  Your 
application  tells  QuickDraw  n  that  it  will  follow  these  fast  port  rules  by  setting  a  bit  in  the 
masterSCB  passed  to  QDStartup. 

The  masterSCB  now  has  the  following  format: 

f  useshadowing      bit  15       Controls  use  of  hardware  shadowing  by  QuickDraw 


II: 


Reserved 
SCB 


fFastPortAware 


bits  8-13 
bits  0-7 


bit  14 


0  -  No  shadowing 

1  -  Shadowing 

Indicates  whether  application  follows  fast  port  rules: 

0  -  Does  not  use  fast  port  rules 

1  -  Does  use  fast  port  rules 
Must  be  set  to  0 

Use  standard  SCB  values 
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New  font  header  layout 

The  font  header  has  been  expanded  to  include  a  new  field  containing  additional 
addressing  information.  Figure  43-1  shows  the  new  layout  for  the  font  header.  For 
information  about  the  old  fields,  see  Chapter  l6,  "QuickDraw  n,"  in  Volume  2  of  the 
Toolbox  Reference. 


m  Figure  43-1  New  font  header  layout 


$00 

OffsetToMF 

Wrod— Offset  in  words  to  Macintosh  font  part 

$02 

family 

Word— Font  faniiiy  nuniber 

$04 

style 

Word— Style  font  was  designed  with 

$06 

size 

Word— Point  size 

$08 

version 

Word— Version  number  of  the  font  defmition 

$0A 

fbrExtent 

Word— Font  bounds  rectangle  extent 

$0C 

highowTLoc 

Word— High-order  word  of  address  to  offset/width  table 

$0E 

Bytes— Additional  fields,  if  any 

highowTLoc      Defines  the  high-order  word  of  the  address  to  the  offset/width  table 
for  the  font.  The  owtloc  field  contains  the  low-order  word  of  the 
address.  Together,  these  two  fields  form  a  full  32-bit  address. 
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Chapter  44  QuickDraw  n  Auxiliary  Update 


This  chapter  documents  new  features  in  QuickDraw  11  Auxiliary.  The 
complete  reference  to  QuickDraw  II  Auxiliary  is  in  Volume  2,  Chapter  17 
of  the  Apple  IlGS  Toolbox  Reference. 
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New  features  in  QuickDraw  n  Auxiliary 

■  QuickDraw  II  now  supports  text  justification  within  pictures.  Note  that  QuickDraw  II 
justifies  the  text  only  when  drawing  the  picture,  not  in  the  stored  picture  image.  You 
control  text  justification  in  pictures  by  setting  a  bit  flag  in  the  f  ontFiags  word  of 
the  GrafPort  record.  Use  the  setFontFiags  tool  call  to  change  the  state  of  this  bit. 

The  f  ontFiags  word  is  defined  as  follows: 

Reserved  bits  4-15  Must  be  set  to  0 

f  Text  Just      bit  3  Controls  text  justification  in  pictures: 

0  -  No  text  justification 

1  -  Justify  text 

bits  0-2  Use  standard  f  ontFiags  values  (see  page  l6- 

56  in  the  Toolbox  Reference  for  a  description  of 
these  bits) 
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New  QuickDraw  n  Auxiliary  calls 

Two  new  QuickDraw  II  tool  calls,  caicMask  and  seedFiii,  provide  enhanced 
functionality  to  the  application  programmer  who  wants  to  create  graphics  entry  or  editing 
software.  A  third  new  call,  SpeciaiRect,  provides  a  high-performance  rectangle  frame 
and  fill  operation. 


CaicMask  $0£12 

Generates  a  mask  from  a  specified  source  image  and  pattern,  by  filling  inward  from  the 
bounding  rectangle.  The  shape  of  the  resulting  mask  consists  of  all  areas  in  the  source 
image  where  leaking  does  not  occur  (all  enclosed  areas  within  the  rectangle): 


This  call  differs  from  seedFiii  only  in  that  it  works  from  the  "outside  in",  whereas 
seedFiii  goes  "inside  out",  filling  all  enclosed  areas  starting  from  a  specified  interior 
point  (see  "seedFiii"  in  this  chapter  for  details). 


Source  rect 


Source  image 


Computed 

CaicMask  shape 
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caicMask  is  most  commonly  used  to  implement  a  lasso  tool,  by  having  caicMask 
determine  the  selected  shape  by  filling  inward  from  the  lasso  rectangle: 


Source  image       Computed  Write  pattern  Destination  image  Destination  is 

CaicMask  shape  was-l,this  containing  anything  now  a  I's  active  mask 

indicates  all  I's  (it  will  be  preinitialized) 


For  this  use,  set  the  call  parameters  as  follows: 

destMode  portion  of  resMode    %0010  (dear  destination  to  zeroes  before  drawing) 

pattemPtr  $FFFFFFFF  (use  all  ones  pattern  when  drawing  to 

destination) 

This  call  does  not  perform  automatic  scaling;  therefore,  the  source  and  destination 
rectangles  must  be  of  equal  size.  In  addition,  note  that  the  fill  is  not  clipped  to  the  current 
port,  and  that  the  resulting  image  cannot  be  stored  into  a  QuickDraw  II  picture. 

A  Important     Your  application  must  word-align  both  the  source  and  destination 
rectangles  in  order  to  assure  an  accurate  fill,  a 
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Parameters 

Stack  before  call 


Previous  contents 


-  srcLocInfoPtr  - 


srcReci 


-  destLocInfoPtr  - 


destRect 


resMode 


-  pattemPtr 


leakTblPtr  - 


Stack  after  call 


Long— Pointer  to  source  locinf  o  data  record 
Long— Pointer  to  source  rectangle  data  record 
Long— Pointer  to  destination  locinf  o  data  record 

Long— Pointer  to  destination  rectangle  data  record 
Word— Resolution  mode 
Long— Pointer  to  fill  pattern 

Long— Pointer  to  leak-through  color  table 
<— SP 


Previous  contents 


Errors 


$0201 
$1211 


<— SP 

memErr 
badRectSize 


$1212  destModeError 


NewHandle  error  occurred 

1)  Height  or  width  is  negative, 

2)  destRect  not  same  size  as 
srcRect,  or  3)  source  or 
destination  rectangle  not  within 
its  boundary  rectangle 
destMode  portion  of  resMode 
invalid 


extern  pascal  void  CalcMask (srcLocInf oPtr,  srcRect, 
destLocInfoPtr,  destRect,  resMode, 
patternPtr,   leakTblPtr) ; 

Pointer      srcLocInf oPtr,   srcRect,  destLocInfoPtr, 

destRect,  patternPtr,  leakTblPtr; 
Word  resMode; 
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srcLocInfoPtr       Points  toaiocinfo  data  record  containing  the  definition  for  the 
source  rectangle  for  the  fill  operation. 

srcRect  Points  to  a  rectangle,  in  local  coordinates,  that  contains  the  source 

pixel  image. 

destLocInfoPtr,  destRect 

Refer  to  output  locinf  o  record  and  rectangle,  respectively.  These 
fields  allow  you  to  copy  the  output  to  a  different  location  in  a 
different  rectangle.  If  you  want  the  output  of  the  operation  to  overiay 
the  input  image,  set  the  source  and  destination  pointers  to  the  same 
values. 


resMode 


destMode 


Reserved 


res 


Indicates  the  resolution  mode  for  the  fill  as  well  as  initialization  and 
drawing  options; 

bits  12-15  Indicates  initialization  and  drawing  options: 

0000  -  copy  source  to  destination  (obliterating 
destination) 

0001  -  leave  destination  alone  (overlay  source  onto 
destination) 

0010  -  initialize  destination  to  zeroes  before  drawing 

0011  -  initialize  destination  to  ones  before  drawing 
other  values  are  invalid 


bits  2-11    Must  be  set  to  0 

bits  0-1     Indicates  the  resolution  for  the  operation: 

00  -  640  pure 

01  -  640  dithered 

10  -  320  mode 

11  -  invalid 

pattemPtr  Pointer  to  the  fill  pattern  for  the  operation,  or  flag  specifying  special 

fill  pattern: 

NIL  Use  an  all  zeroes  pattern  when  writing  to  destination 

$FFFFFFFF  Use  an  all  ones  pattern  when  writing  to  destination 

Other  Assumed  to  be  valid  pointer  to  fill  pattern 
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leakTblPtr  Pointer  to  a  structure  that  defines  the  colors  to  be  covered.  The 

structure  contains  a  count  word,  indicating  the  number  of  color 
entries  in  the  table,  and  a  color  entry  for  each  color  to  be  leaked.  Each 
color  entry  contains  the  offset  into  the  color  table  for  that  color. 


$00 

—             count  — 

Word— Count  of  color  entries  to  follow 

$02 

colorEntries 

count  Words— Offset  into  color  table  for  each  color 
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SeedFill  $0D12 


Generates  a  mask  from  a  specified  source  image  and  pattern,  by  filling  outward  from  a 
starting  point  within  the  source  image.  The  shape  of  the  resulting  mask  consists  of  the 
enclosed  area  in  the  source  image  surrounding  the  starting  (or  seed)  point: 


Source  image  Computed 

SeedFill shapc 


This  call  differs  from  caicMask  only  in  that  it  works  from  the  "inside  out",  whereas 
CaicMask  goes  "outside  in"  (see  "caicMask"  in  this  chapter  for  details). 
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seedFiii  is  a  versatile  tool.  Most  simply,  you  can  use  it  to  implement  a  paint  bucket 
tool: 


Source  image      Computed  Write  pattern  Original  source         Source  image 

SeedFili  shape  image  (passed  with  pattern  added 

again  as  destination) 


For  this  operation,  use  the  following  call  parameter  values: 

destMode  portion  of  resMode    %0001  (do  not  change  destination  image  before 

drawing) 

patternPtr  Pointer  to  fill  color  or  pattern 
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In  order  to  add  an  undo  capability  to  the  paint  bucket,  specify  a  different  destination: 


Source  image       Computed  Write  pattern        Destination  image  Destination  now 

SeedFili  siiapc  containing  anytiiing  contains  filled 

(it  will  be  completely  copy  of  source 
overwritten) 
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As  a  more  complex  example,  consider  this  "from  the  inside"  lasso  tool: 


Source  image      Computed  Write  pattern       Destination  image         Destination  is  now 

SeedFiii  shape    was-l,this         containing  anything       a  I's  active  mask 
indicates  all!  's     (it  will  be  preinitial  ized) 


For  this  operation,  use  the  following  call  parameter  values: 

destMode  portion  of  resMode    %0010  (clear  destination  to  zeroes  before  drawing) 
patternPtr  $FFFFFFFF  (use  all  ones  pattern  when  drawing  to 

destination) 

This  call  does  not  perform  automatic  scaling;  tiierefore,  die  source  and  destination 
rectangles  must  be  of  equal  size.  In  addition,  note  tiiat  the  fill  is  not  clipped  to  tiie  current 
port,  and  tiiat  die  resulting  image  cannot  be  stored  into  a  QuickDraw  II  picture. 

A  Important     Your  application  must  word-align  botii  die  source  and  destination 
rectangles  in  order  to  assure  an  accurate  fill,  a 
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Parameters 

Stack  before  call 


Previous  contents 


-  srcLocInfoPtr 


srcRect 


-  destLocInfoPtr  - 


destRect 


seedH 


seedV 


resMode 


pattemPtr 


-     leakTblPtr  - 


Stack  after  call 


Long— Pointer  to  source  locinf  o  data  record 
Long— Pointer  to  source  rectangle  data  record 
Long— Pointer  to  destination  locinf  o  data  record 
Long— Pointer  to  destination  rectangle  data  record 

Word— Horizontal  offset  (pixel)  to  starting  fill  point 
Word— Vertical  offset  (pixel)  to  starting  fill  point 
Word— Resolution  mode 

Long— Pointer  to  fill  pattern 

Long— Pointer  to  leak-through  color  table 

<— SP 


Previous  contents 


Errors 


$0201 
$1211 


<— SP 

memErr 
badRectSize 


$1212  destModeError 


NewHandle  error  occurred 

1)  Height  or  width  is  negative, 

2)  destRect  not  same  size  as 
srcRect,  or  3)  source  or 
destination  rectangle  not  within 
its  boundary  rectangle 
destMode  portion  of  resMode 
invalid 
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extern  pascal  void  SeedFill (srcLocInf oPtr,  srcRect, 
destLocInf oPtr,  destRect,   seedH,  seedV, 
resMode,  patternPtr,  leakTblPtr) ; 


Pointer 


Word 


srcLocInf oPtr,   srcRect,  destLocInf oPtr, 
destRect,  patternPtr,  leakTblPtr; 
seedH,  seedV,  resMode; 


srcLocInf oPtr       Points  toaiocinfo  data  record  containing  the  definition  for  the 
source  rectangle  for  the  fill  operation. 

srcRect  Points  to  a  rectangle,  in  local  coordinates,  that  contains  the  source 

pixel  image. 

destLocInfoPtr,  destRect 

Refer  to  output  locinf  o  record  and  rectangle,  respectively.  These 
fields  allow  you  to  copy  the  output  to  a  different  location  in  a 
different  rectangle.  If  you  want  the  output  of  the  operation  to  overlay 
the  input  image,  set  the  source  and  destination  pointers  to  the  same 
values. 


seedH,  seedV 


resMode 


destMode 


Reserved 


res 


Specify  the  horizontal  and  vertical  offsets  into  the  source  pixel  image 
of  the  point  at  which  to  start  the  fill  operation. 

Indicates  the  resolution  mode  for  the  fill  as  well  as  initialization  and 
drawing  options: 

bits  12-15  Indicates  initialization  and  drawing  options: 

0000  -  copy  source  to  destination  (obliterating 
destination) 

0001  -  leave  destination  alone  (overlay  source  onto 
destination) 

0010  -  initialize  destination  to  zeroes  before  drawing 

0011  -  initialize  destination  to  ones  before  drawing 
other  values  are  invalid 

bits  2-11    Must  be  set  to  0 

bits  0-1     Indicates  the  resolution  for  the  operation: 

00  -  640  pure 

01  -  640  dithered 

10  -  320  mode 

11  -  invalid 
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patternPtr  Pointer  to  the  fill  pattern  for  the  operation,  or  flag  specifying  special 

fill  pattern: 

Use  an  all  zeroes  pattern  when  writing  to  destination 
Use  an  all  ones  pattern  when  writing  to  destination 
Assumed  to  be  valid  pointer  to  fill  pattern 

leakTblPtr  Pointer  to  a  structure  that  defines  the  colors  to  be  covered.  The 

structure  contains  a  count  word,  indicating  the  number  of  color 
entries  in  the  table,  and  a  color  entry  for  each  color  to  be  leaked.  Each 
color  entry  contains  the  offset  into  the  color  table  for  that  color: 


$00 

count 

Word— Count  of  color  entries  to  follow 

$02 

colorEntries      :  Count  Words— Offset  into  color  uble  for  cach  color 
j 
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SpecialRect  $0C12 

Frames  and  fills  a  rectangle  in  a  single  call,  making  separate  calls  to  FrameRect  and 
FiiiRect  unnecessary. 

The  pen  used  to  draw  the  rectangle  frame  in  640  mode  is  2  pixels  wide  and  1  pixel  high;  in 
320  mode,  the  pen  is  1  pixel  wide  and  1  pixel  high. 

Parameters 

Stack  before  call 


Previous  contents 


recPtr 


frameColor 


fillColor 


Stack  after  call 


Long — Pointer  to  rectangle  to  draw 

Word— Color  of  rectangle  frame 
Word— Color  of  rectangle  interior 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  SpecialRect (recPtr,  frameColor, 
fillColor) ; 

Pointer  recPtr; 

Word  frameColor,  fillColor; 

frameColor,  fillColor 

The  low-order  four  bits  of  each  of  these  parameters  specify  the  color. 
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Chapter  45  Resource  Manager 


This  chapter  documents  the  features  of  the  new  Resource  Manager.  This 
is  a  new  tool  set,  not  previously  documented  in  the 
Apple  IIGS  Toolbox  Reference. 
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About  the  Resource  Manager 

The  Resource  Manager  provides  applications  access  to  resources,  which  can  contain  such 
items  as  menus,  fonts,  and  icons.  Most  basically,  a  resource  is  a  formatted  collection  of 
data.  The  Resource  Manager  does  not  know  the  format  or  content  of  any  given  resource. 
Your  application  defines  the  content  of  its  resources,  or  may  use  standard  resources 
defined  by  the  system.  Resource  Manager  facilities  allow  applications  to  create,  use,  and 
manipulate  these  resources. 

Generally,  your  program  will  access  the  Resource  Manager  indirectly,  as  a  result  of  using 
other  tool  sets,  such  as  the  Window  Manager  or  Control  Manager,  which  use  resources. 
However,  if  your  program  manages  its  own  resources,  it  will  have  to  issue  some  Resource 
Manager  calls  directly.  Further,  you  may  want  to  write  a  program  that  creates  and  edits 
resources.  Such  a  program  would  make  thorough  use  of  Resource  Manager  tool  calls. 

The  following  table  summarizes  the  capabilities  of  the  Resource  Manager  in  a  grouped 
listing  of  its  tool  calls.  Later  sections  of  this  chapter  discuss  resources  in  greater  detail, 
and  define  the  precise  syntax  for  the  Resource  Manager  tool  calls. 

Routine  Description 

Housekeeping  routines 

ResourceBootinit  Called  Only  by  the  Tool  Locator— must  not  be  called  by 

an  application 

Resourcestartup  Informs  the  Resource  Manager  that  an  application 

wants  to  use  its  facilities 
ResourceShutDown  Informs  the  Resource  Manager  that  an  application  is 

finished  using  resource  tool  calls 
ResourceReset  Called  only  when  the  system  is  reset— must  not  be  called 

by  an  application 

ResourceVersion  Retums  the  Resource  Manager  version  number 

Resourcestatus  Returns  the  Resource  Manager's  operational  status 
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Resource  access  routines 


AddResource 

RemoveResource 
LoadResource 
LoadAbsResource 
GetlndResource 

ReleaseResource 
DetachResource 


WriteResource 

Resource  maintenance  routines 


Creates  a  new  resource  and  adds  it  to  a  specified 
resource  file 

Deletes  a  resource  from  a  resource  file 

Loads  a  resource  into  memory 

Loads  a  resource  into  a  specified  memory  location 

Loads  a  resource  given  an  index  into  a  specified 

resource  type 

Removes  a  loaded  resource  from  memory 
Removes  a  loaded  resource  from  the  control  of  the 
Resource  Manager,  but  leaves  the  resource  in  memory 
Writes  a  changed  resource  to  its  resource  file 


GetResourceAttr 

SetResourceAttr 

GetResourceSize 

MarkResourceChange 

SetResourcelD 

UniqueResourcelD 

CountTypes 

GetlndTypes 

CountResources 
MatchResourceHandle 
ResourceConverter 
SetResourceLoad 


Returns  the  attributes  of  a  resource 

Sets  the  attributes  of  a  resource 

Returns  the  size  in  bytes  of  a  resource 

Sets  the  value  of  the  changed  attribute  of  a  resource 

Changes  the  ID  of  a  resource 

Obtains  a  unique  resource  ID  for  a  resource  of  a 
specified  type 

Returns  the  number  of  different  resource  types  in  all 

open  resource  files  for  an  application 

Returns  a  resource  type  value  associated  with  an  index 

into  the  array  of  all  active  resource  types 

Returns  the  number  of  resources  of  a  specified  type 

Finds  the  ID  and  type  of  a  resource,  given  its  handle 

Installs  resource  converter  routines 

Controls  whether  the  Resource  Manager  loads  resources 

from  disk 
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Resource  file  routines 


CreateResourceFile 
OpenResourceFile 

CloseResourceFile 
UpdateResourceFile 


GetCurResourceFile 
SetCurResourceFile 
SetResourceFileDepth 

GetOpenFi leRe  f Num 

HomeResourceFile 

GetMapHandle 


Creates  and  initializes  a  resource  file 

Opens  a  resource  file  for  access  by  the  Resource 

Manager 

Closes  an  open  resource  file 

Writes  all  in-memory  resource  changes  to  the 

appropriate  resource  file,  making  those  changes 

permanent 

Returns  the  file  ID  of  the  current  resource  file 
Sets  the  current  resource  file 
Sets  the  number  of  resource  files  that  the  Resource 
Manager  will  search  when  locating  a  specific  resource 
Returns  the  GS/OS  file  reference  number  for  an  open 
resource  file 

Returns  the  file  ID  of  the  resource  file  that  contains  a 
specified  resource 

Returns  the  handle  of  a  resource  map  for  an  open 
resource  file 


Application  switching  routines 


GetCurResourceApp 


SetCurResourceApp 


Returns  the  User  ID  of  the  application  currently  using 
the  Resource  Manager 

Sets  the  User  ID  of  the  application  now  using  the 
Resource  Manager 
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About  resources 

A  resource  is  a  formatted  collection  of  data,  such  as  a  menu,  a  font,  or  a  program  itself. 
The  format  of  the  data  in  a  resource  is  determined  by  the  program  that  uses  the  resource, 
or  by  the  system  for  standard  resources.  A  program  maintains  its  resources  separate  from 
the  program  code  itself.  This  very  separation  is  the  primary  benefit  of  using  resources- 
program  code  is  immune  to  data  content  changes,  and  program  data  is  immune  to 
program  code  changes,  even  to  changes  in  programming  language. 

Resources,  in  turn,  are  grouped  into  resource  files,  which  correspond  to  tiie  resource 
forks  of  GS/OS  files.  A  given  resource  file  may  contain  one  or  more  resources  of  various 
format.  An  application  that  uses  resources  may  store  tiiose  resources  in  its  own  resource 
file,  or  may  access  resources  in  a  resource  file  that  is  not  directiy  associated  with  the 
program.  The  Resource  Manager  provides  routines  to  access  and  manipulate  resources  in  a 
resource  file. 

You  can  create  the  resource  fork  for  your  program  in  a  variety  of  ways.  Resource  compilers 
convert  text-based  resource  definitions  into  resources  in  a  valid  resource  file.  You  can  use 
an  existing  resource  compiler,  or  you  can  create  your  own.  Alternatively,  you  can  write  a 
program  that  creates  a  resource  file  and  its  resources,  using  Resource  Manager  tool  calls. 
Finally,  resource  editors  allow  you  to  create  resources  interactively. 


Identifying  resources 

Programs  identify  resources  witii  a  resource  specification  consisting  of  a  resource  type 
and  a  resource  ID  number.  The  resource  type  (or  just  type)  defines  a  class  or  group  of 
resources  tiiat  share  a  common  format.  The  resource  ID  (or  just  ID)  uniquely  identifies  a 
specific  resource  of  a  given  type.  Taken  together,  the  resource  type  and  ID  completely 
identify  the  resource  and  define  its  format.  The  ID  for  a  resource  must  be  unique  within 
the  context  of  its  type;  however,  the  same  ID  number  may  be  used  for  resources  of 
different  type. 
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Resource  types 

The  resource  type  defines  a  class  of  resources  that  share  a  common  format.  The  system 
defines  several  standard  types  for  resources  used  to  interact  with  system  or  toolbox 
functions.  These  standard  types  and  the  formats  of  their  associated  resources  are 
documented  in  Appendix  E,  "Resource  Types,"  in  this  book.  In  addition,  your  program 
may  define  unique  resource  types  for  its  custom  resources.  Since  the  Resource  Manager 
knows  nothing  about  the  format  or  content  of  the  resources  it  manages,  you  have 
complete  freedom  to  define  the  resources  you  need. 

The  resource  type  is  a  word  value.  The  following  table  summarizes  valid  resource  type 
values: 


Type  value  range  Use 

$0000  Invalid  resource  type;  do  not  use 

$0001  through  $7FFF  Available  for  application  use 

$8000  through  $FFFF  Reserved  for  system  use 


Resource  IDs 

The  resource  ID  uniquely  identifies  a  particular  resource  of  a  given  type  in  a  resource  file. 
Every  resource  in  a  resource  file  must  have  an  ID  value  that  is  unique  within  the  context  of 
its  resource  type.  Resources  of  different  type  may,  however,  have  the  same  ID  value. 

The  resource  ID  is  a  long  value.  Even  though  the  resource  ID  is  only  meaninghil  in  the 
context  of  a  given  resource  type,  the  system  does  place  restrictions  on  the  ID  values  you 
can  assign.  The  following  table  summarizes  the  allowable  ranges  for  ID  values: 

D)  value  range  Use 

$00000000  Invalid  resource  ID;  do  not  use 

$00000001  through  $07FEFFFF     Available  for  application  use 
$07FF0000  through  $07FFFFFF     Reserved  for  system  use 
$08000000  through  $FFFFFFFF     Invalid  values;  do  not  use 

When  creating  a  new  resource,  use  the  uniqueResourceiD  tool  call  to  obtain  a  resource 
ID.  The  Resource  Manager  will  allocate  a  new,  unique  resource  ID  for  you.  You  can  force 
the  ID  to  fall  within  a  desired  range,  in  order  to  group  resources  by  resource  ID  within 
resource  type.  Each  ID  range  contains  65,535  possible  values.  The  ID  range  value  provides 
the  high-order  word  of  the  long-word  resource  ID.  The  following  table  summarizes  the 
allowable  ranges: 


45-6     Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


ID  Range 


Lowest  possible  ID  returned 


Highest  possible  ID  returned 


$0000 
$0001 
$0002 


$00000001  (NIL  is  invalid) 

$00010000 

$00020000 


$0000FFFF 
$0001FFFF 
$0002FFFF 


(and  so  on) 


$07FE  $07FE0000  $07FEFFFF 

$07FF  Reserved  for  system  use 

$0800-$FFFE  Invalid  range  values 

$FFFF  $00000001  $07FEFFFF 


(directs  Resource  Manager  to  allocate  from  any  application  range) 


Resource  Names 

As  an  alternative  to  identifying  a  resource  of  a  given  type  by  an  ID,  you  may  choose  to 
assign  it  a  resource  name.  Your  application  may  then  use  the  resource  type  and  name 
combination  to  uniquely  identify  the  resource.  In  some  cases,  this  may  be  more  handy 
than  using  the  numeric  ID.  The  resource  name  must  be  unique  within  the  context  of  a  given 
resource  type.  You  should  note  that  the  Resource  Manager  does  not  provide  call-level 
support  for  resource  names.  However,  the  rResName  resource  ($8014)  defines  the 
standard  layout  for  resource  names.  If  you  choose  to  use  resource  names,  or  you  use 
developer  tools  that  support  named  resources,  you  should  be  careful  to  use  the  standard 
data  structures  for  defining  those  names. 
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Using  resources 

In  most  cases,  applications  only  use  the  Resource  Manager  indirectly,  by  using  other  tool 
sets  that,  in  turn,  use  resources  to  store  their  data  structures.  Even  if  your  program  defines 
resources,  either  for  its  own  data  or  for  data  to  be  used  by  the  system,  it  will  have  to  issue 
only  a  few  Resource  Manager  calls  to  use  those  resources.  However,  programs  that  create 
and  manipulate  resources  and  resource  files  must  use  far  more  Resource  Manager 
functionality.  The  next  several  paragraphs  describe  the  steps  your  program  must  follow  in 
order  to  use  its  predefined  resources. 

1 .  Unlike  most  other  tool  sets,  your  program  does  not  have  to  start  the  Resource 
Manager.  At  startup  time,  the  system  automatically  loads  and  initializes  the  Resource 
Manager  from  the  RESOURCE.MGR  file  in  the  SYSTEM.SETUP  directory  of  the  boot 
disk.  The  Resource  Manager  then  opens  the  system  resources  file,  SYS.RESOURCES  in 
the  SYSTEM.SETUP  directory,  if  it  is  present. 

2.  To  use  the  Resource  Manager,  you  program  must  log  in,  using  the  Resourcestartup 
tool  call.  This  call  informs  the  Resource  Manager  that  your  program  is  going  to  be  using 
its  services.  As  an  alternative,  your  program  may  issue  the  Tool  Locator 
StartUpTools  call. 

3.  Issue  the  openResourceFiie  tool  call  to  open  each  resource  file  for  your 
application.  If  your  program  issued  the  Tool  Locator  start  up  Tools  call,  then  it 
need  not  explicidy  open  its  resource  fork  before  trying  to  use  resources  located  there. 
If,  on  the  other  hand,  your  program  used  the  Resourcestartup  tool  call,  then  it 
must  issue  an  openResourceFiie  call  for  its  resource  fork  before  accessing  any 
resources  stored  there. 

4.  As  part  of  termination  processing,  call  ResourceShutDown  to  log  out  from  the 
Resource  Manager.  The  Resource  Manager  will  automatically  close  any  open  resource 
files.  Once  your  program  has  issued  a  ResourceShutDown  call,  it  should  not  make 
any  other  Resource  Manager  calls,  except  for  Resourcestartup. 


#- 
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Resource  attributes 

Every  resource  has  an  associated  set  of  attributes  that  define  the  current  state  of  the 
resource  as  well  as  limits  on  how  the  resource  can  be  used.  The  Resource  Manager  stores 
these  attributes  in  an  attributes  flag  word  (or  Attributes  word)  for  the  resource 
(specifically,  the  resAttr  field  in  the  resource  reference  record).  Your  program  can  read 
and  write  this  attribute  word  by  means  of  the  GetResourceAttr  and 
SetResourceAttr  tOol  calls.  In  addition,  the  MarkResourceChange  tOOl  call 
provides  a  convenient  mechanism  for  changing  the  setting  of  the  changed  flag  for  the 
resource,  which  indicates  whether  the  resource  has  been  changed  since  it  was  read  from 
disk. 

Many  of  the  attributes  govern  the  type  of  memory  used  to  store  the  resource  when  the 
Resource  Manager  reads  it  in  from  disk.  These  attributes  direcdy  correspond  to  flags  in 
the  Memory  Manager  NewHandie  tool  call  memory  Attributes  word.  When  it  allocates 
memory  for  a  resource  to  be  loaded  from  disk,  the  Resource  Manager  masks  out  the  other 
bits  and  passes  the  Attributes  word  to  the  NewHandie  call.  See  the  NewHandie  tool 
description  in  Chapter  12,  "Memory  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for  the 
format  and  content  of  the  memory  Attributes  word. 

The  following  table  describes  the  content  of  the  attribute  word  for  a  resource: 

attrLocked  Bit  15       Passed  to  Memory  Manager  NewHandie  tool  call 

when  memory  is  allocated  for  the  resource: 
1  -  Memory  for  resource  locked;  cannot  be  moved  or 
purged 

0  -  Memory  for  resource  not  locked 
attrFixed            Bit  14       Passed  to  Memory  Manager  NewHandie  tool  call 

when  memory  is  allocated  for  the  resource: 

1  -  Memory  for  resource  is  fixed  and  cannot  be  moved 

0  -  Memory  for  resource  need  not  be  fixed 
Reserved               Bits  12-13  Must  be  set  to  0, 

resConverter        Bit  11       Indicates  whether  the  resource  requires  a  resource 

converter  routine  (see  "Resource  converter  routines" 
later  in  this  chapter  for  more  information): 

1  -  Resource  requires  a  converter  routine 

0  -Resource  does  not  require  a  converter  routine 
resAbsLoad          Bit  10       Govems  whether  the  resource  must  be  loaded  at  a 

specific  memory  location.  Resources  that  must  be 
loaded  at  an  absolute  location  must  be  created  by  a 
resource  editor  or  compiler. 

1  -  Resource  to  be  loaded  at  specific  location 

0  -  Resource  need  not  be  loaded  at  a  specific  location 
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attrPurge 


resProtected 


resPreLoad 


resChanged 


attrNoCross 


attrNoSpec 


attrPage 


Reserved 


Bits  8-9     Passed  to  Memory  Manager  NewHandie  tool  call 
when  memory  is  allocated  for  the  resource: 
11  -  Purge  level  3 
10 -Purge  level  2 
01  -  Purge  level  1 
00 -Purge  level  0 

Bit  7        Indicates  whether  the  resource  is  write-protected.  If 
set  to  1,  then  applications  may  not  update  the 
resource  on  disk: 
1  -  Resource  is  write-protected 

0  -  Resource  is  not  write-protected 

Bit  6        Specifies  whether  the  Resource  Manager  should  load 
the  resource  into  memory  at  openResourceFiie 
time.  If  set  to  1,  then  this  resource  will  be  loaded  into 
memory  when  the  resource  file  is  opened,  rather  than 
when  the  resource  itself  is  accessed: 

1  -  Preload  the  resource 

0  -  Do  not  preload  the  resource 

Bit  5        Indicates  whether  the  resource  has  been  changed.  If 
set  to  1  for  a  non-write-protected  resource,  the 
Resource  Manager  will  update  the  resource  on  disk  at 
CloseResourceFile  time: 

1  -  Resource  has  been  changed  in  memory,  and 
therefore  differs  from  the  version  stored  on  disk 

0  -  Resource  has  not  been  changed  in  memory 
Bit  4        Passed  to  Memory  Manager  NewHandie  tool  call 

when  memory  is  allocated  for  the  resource: 

1  -  Memory  may  not  cross  bank  boundary 

0  -  Memory  may  cross  bank  boundary 

Bit  3        Passed  to  Memory  Manager  NewHandie  tool  call 
when  memory  is  allocated  for  the  resource: 

1  -  May  not  use  special  memory 

0  -  May  use  special  memory 

Bit  2        Passed  to  Memory  Manager  NewHandie  tool  call 
when  memory  is  allocated  for  the  resource: 

1  -  Memory  must  be  page-aligned 

0  -  Memory  need  not  be  page-aligned 
Bits  0-1     Must  be  set  to  0 
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Resource  file  format 

A  resource  file  is  not  a  file  in  the  strictest  sense;  actually,  it  is  one  of  two  parts,  or  forks,  of 
a  GS/OS  file.  Every  file  has  a  resource  fork  and  a  data  fork,  either  of  which  may  be  empty. 
The  data  fork  contains  information  for  the  application  as  well  as  the  application  code 
itself,  and  is  formatted  according  to  the  needs  of  the  application.  Programs  manipulate 
data  in  the  data  fork  with  GS/OS  file  system  calls. 

The  Resource  Manager  defines  the  format  of  the  resource  fork.  Programs  read  and 
manipulate  resources  with  Resource  Manager  tool  calls.  As  a  result,  applications  do  not 
need  to  know  the  format  of  the  resource  fork  to  use  the  resources  stored  there.  You  can 
create  resources  and  load  them  into  a  resource  file  with  the  aid  of  a  Resource  Editor,  or 
with  whatever  tools  are  available  in  your  development  environment. 

A  resource  file  consists  primarily  of  resource  data  and  a  resource  map.  The  resources 
themselves  comprise  the  resource  data.  The  resource  map  is  a  directory  to  those 
resources,  containing  both  location  and  size  information.  Each  entry  in  the  map  on  disk 
contains  the  offset  of  the  resource  into  the  file;  in  memory,  the  entry  contains  a  handle  to 
the  resource  if  it  is  loaded.  The  Resource  Manager  reads  the  resource  map  into  memory  at 
resource  file  open  time,  and  maintains  it  in  memory  until  the  file  is  closed. 


Resource  File  IDs 

an  application  opens  a  resource  file,  the  Resource  Manager  assigns  that  open  file  a  file  ID, 
which  identifies  the  file  to  the  Resource  Manager.  Every  open  resource  file  has  a  file  ID 
that  is  unique  in  the  entire  system.  Many  Resource  Manager  tool  calls  require  the  file  ID  in 
order  to  identify  the  resource  file  to  be  accessed.  The  file  ID  for  the  system  resource  file  is 
always  $0001  (sysFiieio). 

The  openResourceFiie  tool  call  retums  the  file  ID  for  a  resource  file.  Note  that  the  file 
ID  does  not  correspond  to  the  GS/OS  file  reference  number.  Use  the 
GetopenFiieRef  Num  Resource  Manager  tool  call  to  obtain  the  GS/OS  file  number  for  a 
resource  file. 
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Resource  file  search  sequence 

As  your  program  opens  resource  files,  the  Resource  Manager  adds  those  files  to  the  head 
of  the  resource  file  search  chain  for  your  application.  The  Resource  Manager  uses  this 
search  chain  for  many  of  its  operations,  such  as  locating  a  resource.  The  system  resource 
file  is  always  the  last  file  in  the  search  sequence.  When  it  runs  the  search  chain,  the 
Resource  Manager  first  checks  all  files  in  the  application  chain,  then  checks  in  the  system 
resource  file,  if  one  is  defined. 

You  control  the  application  file  search  sequence  by  the  order  in  which  your  program  opens 
its  resource  files.  For  example,  if  your  program  issues  the  following  tool  calls: 

OpenResourceFile  File  A 

OpenResourceFile  File  B 

OpenResourceFile  File  C 

Resource  Manager  builds  the  following  search  chain  for  your  application: 


The  most  recently  opened  file  (in  this  example,  File  C)  is  referred  to  as  the  current  resource 
file  (or  simply,  the  current  file).  It  is  also  called  the  first  resource  file  (or  first  file),  since  it 
is  first  file  accessed  during  a  search.  The  least  recently  opened  application  resource  file 
(File  A)  is  called  the  last  resource  file  (or  last  file),  because  it  is  the  last  application  file  to 
be  searched. 
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During  a  search,  which  happens  on  nearly  every  Resource  Manager  tool  call  that  accepts 
resource  type  and  ID  arguments,  the  Resource  Manager  starts  with  the  current  file,  and 
searches  through  the  chain  until  it  either  finds  the  desired  resource  or  exhausts  the  file  list, 
Note  that  the  search  stops  with  the  first  occurrence  of  a  matching  resource;  a  second 
instance  of  a  resource  with  the  same  ID  and  type  will  not  be  found  unless  your  application 
asserts  further  control  over  the  resource  search  sequence. 

The  Resource  Manager  provides  tool  calls  that  allow  your  program  to  control  the  search 
sequence  for  the  resource  file  chain.  The  setcurResourceFiie  tool  call  changes  the 
current  resource  file,  so  that  any  resource  file,  including  the  System  file,  can  be  the  first  file 
searched,  though  the  search  still  terminates  when  the  Resource  Manager  either  finds  the 
desired  resource,  or  hits  the  end  of  the  file  chain.  The  setResourceFiieoepth  tool  call 
controls  the  number  of  files  the  Resource  Manager  will  search  before  giving  up.  By  using 
these  calls,  your  program  can  fine-tune  resource  searches  for  performance  or  can  inhibit 
access  to  some  resource  files  for  some  searches. 


Resource  file  layout  and  data  structures 

This  section  describes  the  format  of  a  resource  file  on  disk.  This  information  is  intended 
only  for  application  programmers  who  are  writing  tools  to  create,  delete,  or  edit  resources 
in  the  resource  fork. 

Figure  45-1  shows  the  internal  layout  of  the  resource  fork  of  a  file.  The  resource  file  header 
is  the  only  data  block  that  resides  at  a  fixed  location  in  the  fork;  it  is  always  the  first  data 
item  in  the  fork.  Along  with  other  control  information,  the  resource  file  header  contains 
the  file  offset  to  the  resource  map.  The  map,  in  turn,  contains  location  and  size 
information  for  each  resource  contained  in  the  file. 
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Figure  45-1     Resource  file  internal  layout 
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Resource  map 
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Resource 


The  Resource  Manager  controls  the  relative  positions  of  all  elements  of  the  resource  fork. 
It  will  move  or  resize  the  map  or  resources  as  required.  Therefore,  your  program  should 
never  rely  on  the  location  of  any  element  in  the  fork,  except  for  the  resource  file  header. 

The  following  sections  present  the  format  of  the  resource  file  header,  resource  map,  and 
their  associated  data  structures  in  greater  detail.  These  descriptions  present  version  0 
layout  infomation.  Future  system  releases  may  support  other  versions  with  different 
layouts.  Your  program  should  check  the  value  in  the  rFiieversion  field  in  the  resource 
file  header  before  manipulating  a  resource  file. 
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Resource  file  header 

The  resource  file  header  is  the  first  data  block  in  every  resource  fork,  and  has  the  following 
format: 


$00 


—  rFlleVerslon 


$04  _ 

—  rFileToMap 


$08 


$0C 


—      rFlleMapSl ze 


Long 


Long 


Long 


rFlleMemo  •  128ByteS 

 i 


rFiieversion  Version  number  defining  layout  of  resource  file.  Currently,  only  version 
0  is  supported.  This  field  allows  IIGS  resource  files  to  be  distinguished 
from  Macintosh  resource  files;  the  first  long  in  Macintosh  resource  files 
must  have  a  value  that  is  greater  than  127. 


rFileToMap 


rFileMapSize 


rFileMemo 


Offset,  in  bytes,  to  beginning  of  the  resource  map.  This  offset  starts 
from  the  beginning  of  the  resource  file. 

Size,  in  bytes,  of  the  resource  map. 

Reserved  for  application  use.  The  Resource  Manager  does  not  provide 
any  facility  for  reading  or  writing  this  field.  Your  program  must  use 
GS/OS  file  system  calls  to  access  the  rFileMemo  field. 
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Resource  map 

The  resource  map  provides  indexes  to  the  resources  stored  in  the  resource  file,  and  is 
formatted  as  follows; 


$00 

- 

mapNext 

- 

Long 

$04 

mapFlag 

- 

Word 

$06 

— 

mapOf fset 

— 

Long 

$0A 

mapSlze 

Long 

$0E 

raapToIndex 

Word 

$10 

mapFileNum 

Word 

$12 

mapID 

Word 

$14 

mapIndexSlze 

Long 

$18 

mapIndexUsed 

Long 

$1C 

mapFreeLl st  Si  ze 

Word 

$1E 

mapFreeLlstUsed 

Word 

$20 

mapFreeList 

Array  of  resource  free  blocks 

$xx 

maplndex 

i 

Array  of  resource  reference  records 

i 

Handle  to  resource  map  for  next  resource  file  in  the  search  chain.  Set 
to  NIL  if  last  file  in  chain.  This  field  is  only  valid  when  the  map  is  in 
memory. 
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mapFlag 


Contains  control  flags  defining  the  state  of  the  resource  file: 


Reserved  bits  2-15    Set  to  0 

mapchanged  bit  1         Indicates  whether  the  resource  map  has  been 

modified,  and  must  therefore  be  written  to  disk 

when  the  file  is  closed: 

1  -  Map  changed 

0  -  Map  not  changed 
Reserved  bit  0        Set  to  0 

mapof  f  set        Offset,  in  bytes,  to  the  resource  map  from  the  beginning  of  the 
resource  file, 

mapsize  Size,  in  bytes,  of  the  resource  map  on  disk.  Note  that  the  memory 

image  of  the  map  may  have  a  different  size  due  to  resource  or 
resource  file  changes  during  program  execution. 

mapToindex      Offset,  in  bytes,  from  beginning  of  map  to  the  beginning  of  the 
mapindex  array  of  resource  reference  records. 

mapFiieNum      GS/OS  file  reference  number.  This  field  is  valid  only  in  memory. 

mapiD  Resource  Manager  file  ID  for  the  open  resource  file.  This  field  is  valid 

only  in  memory. 

mapindexsize  Total  number  of  resource  reference  records  in  mapindex. 
mapindexused  Number  of  used  resource  reference  records  in  mapindex. 
mapFreeListSize 

Total  number  of  resource  free  blocks  in  mapFreeList. 

mapFreeListUsed 

Number  of  used  resource  free  blocks  in  mapFreeList. 

mapFreeList     Array  of  resource  free  blocks,  which  describe  free  space  in  the 
resource  file. 

mapindex         Array  of  resource  reference  records,  which  contain  control  information 
about  the  resources  in  the  resource  file. 
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Resource  free  block 

The  resource  free  block  describes  a  contiguous  area  of  free  space  in  the  resource  file.  The 
resource  map  contains  a  variable-sized  array  of  these  blocks  at  mapFreeList.  Note  that 
each  resource  file  has  at  least  one  resource  free  block,  defining  free  space  from  the  end  of 
the  resource  file  to  $FFFFFFFF.  Each  resource  free  block  has  the  following  format: 


$00 


$04 


-         blkOffset         -  Long 


blkSize  -  Long 


blkOffset        Offset,  in  bytes,  to  the  free  block  from  the  start  of  the  resource  fork. 
A  NIL  value  indicates  the  end  of  the  used' blocks  in  the  array. 

blkSize  Size,  in  bytes,  of  the  free  block  of  space. 
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Resource  reference  record 

The  resource  reference  record  contains  control  information  about  a  resource.  The  resource 
map  contains  a  variable-sized  array  of  these  blocks,  starting  at  the  location  specified  in 
mapToindex.  Each  resource  reference  record  has  the  following  format; 


$00 

resType 

Word 

$02 

resID 

Long 

$06 

resOf fset 

Long 

$0A 

resAttr 

Word 

$0C 

resSlze 

Long 

$10 

resHandle 

Long 

resType  Resource  type.  NIL  value  indicates  last  used  entry  in  the  array. 

resiD  Resource  ID. 

resOf  f  set        Offset,  in  bytes,  to  the  resource  from  the  start  of  the  resource  file. 

resAttr  Resource  attributes.  See  "Resource  attributes"  earlier  in  this  chapter 

for  bit  flag  definitions. 

ressize  Size,  in  bytes,  of  the  resource  in  the  resource  file.  Note  that  the  size  of 

the  resource  in  memory  may  differ,  due  to  changes  made  to  the 
resource  by  application  programs  or  by  resource  converter  routines. 

resHandle        Handle  of  resource  in  memory.  NIL  value  indicates  that  the  resource 
has  not  been  loaded  into  memory.  Your  program  can  determine  the  in- 
memory  size  of  the  resource  by  examining  the  size  of  this  handle. 
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Resource  converter  routines 

The  Resource  Manager  supports  the  concept  of  resource  converter  routines.  Converter 
routines  format  resources  for  access  by  your  program,  allowing  the  memory  format  of  a 
resource  to  differ  from  its  disk  representation.  These  routines  can  be  used,  for  example, 
to  store  resources  in  a  compressed  form  on  disk,  to  reformat  common  resources  for 
different  programs  or  operating  environments,  or  to  perform  code  relocation. 

When  loading  or  unloading  a  resource,  the  Resource  Manager  determines  whether  to 
invoke  a  converter  routine  by  examining  the  resConverter  flag  in  the  Attributes  word 
for  the  resource.  If  that  flag  is  set  to  1,  indicating  that  the  resource  must  be  converted 
before  being  read  or  written,  the  Resource  Manager  invokes  the  appropriate  converter 
routine  for  the  resource  type.  The  converter  routine  may  then  reformat  the  resource  in  any 
way  it  chooses. 

Your  program  registers  a  converter  routine  with  the  ResourceConverter  tool  call.  At 
that  time,  your  program  must  specify  the  resource  type  to  be  handled  by  the  converter 
routine.  One  converter  routine  may  handle  more  than  one  resource  type;  your  program 
must  issue  separate  ResourceConverter  tool  calls  for  each  type  to  be  converted. 

The  Resource  Manager  tracks  resource  converters  in  two  types  of  lists.  Each  application 
has  a  private  application  routine  list,  which  can  contain  up  to  10,922  entries.  In  addition, 
the  Resource  Manager  maintains  a  system  routine  list,  which  is  available  to  all 
applications.  When  searching  for  a  converter  routine  for  a  specific  resource  type,  the 
Resource  Manager  first  checks  the  application  list,  then  the  system  list.  As  a  result,  your 
program  can  override  a  standard  converter  routine  by  registering  a  routine  for  the  same 
resource  type  in  its  application  converter  routine  list.  Applications  should  never  log 
routines  into  or  out  of  the  system  list. 

When  the  Resource  Manager  invokes  a  converter  routine,  it  loads  the  stack  with  values 
specifying  the  operation  to  be  performed  and  any  needed  parameters.  Before  returning 
control  to  the  Resource  Manager,  the  converter  routine  should  set  a  condition  code  in  the 
A  register  (any  nonzero  value  indicates  an  error)  and  retum  the  appropriate  result  value  on 
the  stack.  The  following  sections  provide  detailed  descriptions  of  the  entry  and  exit 
conditions  for  each  converter  routine  operation. 

♦  Note:  Not  all  resource  converters  support  conversion  when  resources  are  written  back 
to  disk.  The  supplied  code  resource  converter  only  functions  on  resource  read 
operations,  for  example.  Consequently,  if  you  are  unsure  about  the  behavior  of  a  given 
resource  converter,  you  should  not  mark  converted  resources  changed,  since  the 
converter  may  write  them  back  to  disk  in  an  unexpected  format. 
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ReadResource 

Read  a  resource  from  disk  into  memory.  The  converter  routine  must  load  the  file  from 
disk  and  perform  any  necessary  reformatting. 

On  entry,  convertParam  contains  a  pointer  to  a  GS/OS  read  file  parameter  block  (see  the 
GS/OS  Reference  for  more  information  on  GS/OS  file  manipulation  and  data  structures). 
The  file  mark  is  set  to  the  beginning  of  the  file  and  the  block  is  set  to  read  the  entire 
resource  from  disk.  In  order  to  read  the  file,  your  program  can  do  the  following: 

pushlong        convertParam  Pointer  to  read  parameter  block 

pushword        $2012  GS/OS  read  command  code 

jsl                  $E100B0  Call  GS/OS 
check  for  errors 

The  resPointer  field  contains  a  pointer  to  the  resource  reference  record,  which 
contains  location  and  size  information  about  the  resource  in  memory  (see  "Resource  file 
format"  earlier  in  this  chapter  for  information  on  the  format  and  content  of  the  resource 
reference  record).  Your  program  should  verify  that  the  number  of  bytes  loaded 
corresponds  to  the  size  of  the  resource  on  disk  (compare  res  size  value  to  the  size  of 
the  handle  that  received  the  resource).  Your  program  should  also  check  to  see  if  the 
resource  must  be  loaded  at  an  absolute  location  (resAbsLoad  flag  set  to  1  in  resAttr 
word  of  the  resource  reference  record).  If  so,  be  careful  to  convert  the  resource  into  the 
appropriate  location. 

If,  during  resource  conversion,  the  converter  routine  must  copy  the  resource  into  a 
different  handle,  the  routine  must  load  that  new  handle  into  the  resHandie  field  of  the 
resource  reference  record,  and  dispose  of  the  original  handle.  Upon  return,  the  handle  to 
the  converted  resource  should  retain  its  original  Memory  Manager  attributes  (locked,  and 
so  on). 

Upon  successful  completion,  the  converter  routine  should  return  a  NIL  Result  vaiue.  In  case 
of  error,  the  routine  should  retum  a  non-NIL  Result,  and  must  free  the  memory  referenced 
by  the  resHandie  field  in  the  resource  reference  record,  and  set  that  field  to  NIL. 
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Parameters 

Stack  before  call 

Previous  contents 

Space 
convertCommand 
-  convertParam  - 
resPointer 


Stack  after  call 

Previous  contents 
Result 


Long— Space  for  result 

Word— Command  to  be  performed  (will  be  0;  readResource) 
Long— Pointer  to  GS/OS  read  file  parameter  block 

Long— Pointer  to  resource  reference  record 
<— SP 


Long— NIL  if  successful;  error  code  if  error  (low-order  word) 
<— SP 
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WriteResource 

Write  a  resource  from  memory  onto  disk.  The  converter  routine  must  perform  any 
necessary  reformatting  and  write  the  file  to  disk. 

On  entry,  convertParam  contains  a  pointer  to  a  GS/OS  write  file  parameter  block  (see 
\htGS/OS  Reference  for  more  information  on  GS/OS  file  manipulation  and  data 
structures).  The  file  mark  is  set  to  the  beginning  of  the  file  on  disk  and  the  block  is  set  to 
write  the  entire  resource.  Before  issuing  a  writeResource  command,  the  Resource 
Manager  will  determine  the  amount  of  disk  space  required  for  the  resource  by  calling  the 
returnDisksize  function  in  the  converter  routine. 

In  order  to  write  the  file,  your  program  can  do  the  following: 

pushlong        convertParam  Pointer  to  read  parameter  block 

pushword        $2013  GS/OS  write  command  code 

jsl  $E100B0  Call  GS/OS 

check  for  errors 

The  resPointer  field  contains  a  pointer  to  the  resource  reference  record,  which 
contains  location  and  size  information  about  the  resource  in  memory  (see  "Resource  file 
formaf  eariier  in  this  chapter  for  information  on  the  format  and  content  of  the  resource 
reference  record).  The  Resource  Manager  will  dispose  of  the  handle  to  the  resource  after 
calling  writeResource. 

This  function  must  return  a  NIL  Result  value. 
Parameters 
Stack  before  call 

Previous  contents 

Space 
convertCommand 
-  convertParam  - 


resPointer 


Long— Space  for  result 

Word— Command  to  be  performed  (will  be  2:  writeResource) 
Long— Pointer  to  GS/OS  write  file  parameter  block 

Long— Pointer  to  resource  reference  record 
<— SP 
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Stack  after  call 


Prmous  contents 


Result 


Long— Must  be  set  to  NIL 
<— SP 
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ReturnDiskSize 

Determines  the  amount  of  space  a  resource  will  require  on  disk,  and  returns  that  value  to 
the  caller.  Note  that  this  call  is  not  valid  for  resources  that  are  loaded  into  absolute 
memory,  since  the  size  of  these  resources  cannot  change. 

The  convertParam  parameter  is  undefined. 

The  resPointer  field  contains  a  pointer  to  the  resource  reference  record,  which 
contains  location  and  size  infomiation  about  the  resource  in  memory  (see  "Resource  file 
formaf  earlier  in  this  chapter  for  information  on  the  format  and  content  of  the  resource 
reference  record). 

On  exit.  Result  contains  the  amount  of  disk  space  required  to  store  the  resource,  in  bytes. 
If  this  new  size  differs  from  the  original  file  size,  the  Resource  Manager  frees  the  old  space 
and  allocates  a  new  file. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


convertCommand 


-  convertParam  - 


resPointer 


Long— Space  for  result 

Word— Command  to  be  performed  (will  be  4:  returnDisksize) 
Long— Undefined 

Long— Pointer  to  resource  reference  record 
<— SP 


Stack  after  call 


Previous  contents 


Result 


Long— Bytes  of  disk  space  required  to  store  resource 
<— SP 
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Application  switchers  and  desk  accessories 

Desk  accessories  and  application-switching  programs  must  be  careful  to  preserve  the 
state  of  the  Resource  Manager  before  using  its  facilities.  The  Resource  Manager  provides 
tool  calls  that  allow  such  programs  to  switch  the  currently  active  Resource  Manager 
application.  The  GetcurResourceApp  tool  call  returns  the  User  ID  of  the  application 
that  is  currently  using  the  Resource  Manager.  This  call  returns  a  special  value  if  the  Resource 
Manager  is  not  in  use.  The  setcurResourceApp  tool  call  changes  the  current 
application,  by  loading  a  new  User  ID  value.  It  is  the  responsiblity  of  the  code  doing  the 
switch  to  use  these  calls. 

In  the  following  example,  the  Resource  Manager  is  already  active  and  the  application 
switcher  has  previously  registered  itself  with  the  Resource  Manager  with  the 
Resourcestartup  tool  call.  The  switching  program  must  save  the  User  ID  of  the 
program  that  is  currently  using  the  Resource  Manager  before  it  issues  any  other  Resource 
Manager  tool  calls: 

/  •  .  Q 

pha  ;  space  for  result  from  GetCurResourceApp 

GetcurResourceApp 

get  current  app  user  ID,   save  on  stack 
pushword  myUserlD  ;  pass  my  user  ID  to  Resource  Manager 
SetcurResourceApp 
;  switch  to  my  resources  and  files 

SetcurResourceApp 

restore  original  application  user  ID 
(saved  on  stack  after  GetCurResourceApp 
;  tool  call) . 

(return  to  caller) 
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In  the  case  where  your  program  must  first  log  into  the  Resource  Manager,  it  must  issue  the 
Resourcestartup  tool  Call  before  Calling  any  other  Resource  Manager  functions: 
;  (on  entry  to  desk  accessory  task  handler) 


NoResMgr 


Prime  for  FALSE  if  Resource  Manager 

is  not  active 
check  for  active  Resource  Manager 

Exit  if  Resource  Manager  not  active 

Space  for  result 


pushword  #0 

ResourceStatus 
pla 

beq  NoResMgr 
pha 

GetCurResourceApp 

get  current  app  user  ID,   save  on  stack 
pushword  myUserlD  ;  pass  my  user  ID  to  Resource  Manager 
SetCurResourceApp 

switch  to  my  resources  and  files 


SetCurResourceApp 


restore  original  application  user  ID 
(saved  on  stack  after  GetCurResourceApp 
tool  call) . 


(return  to  caller) 
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Resource  Manager  housekeeping  routines 

This  section  discusses  the  standard  housekeeping  routines,  in  call  number  order. 

ResourceBootlnit  $011£ 

Initializes  the  Resource  Manager. 

▲  Warning     An  application  must  never  make  this  call,  a 

Parameters        The  stack  is  not  affected  by  this  call.  There  are  no  input  our  output 
parameters. 

Errors  None 

C  Call  must  not  be  made  by  an  application. 
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ResourceStartUp  $021E 

Notifies  the  Resource  Manager  that  an  application  wishes  to  open  and  use  its  own 
resource  files.  Unlike  other  tool  set  startup  calls,  this  call  is  not  required  in  all 
circumstances.  If  your  application  only  uses  system  resources  (located  in  the  system 
resource  file),  then  it  does  not  have  to  issue  a  Resourcestartup  tool  call.  On  the  other 
hand,  if  your  application  uses  non-system  resources,  then  it  must  issue  this  tool  all  prior 
to  opening  those  resource  files. 

If  your  application  issues  this  call,  then  it  must  issue  the  ResourceShutDown  tool  call 
before  quitting. 

Note  that  the  Tool  Locator  start upToois  tool  call  automatically  starts  the  Resource 
Manager. 

Parameters 

Stack  before  call 

Previous  contents 


userlD 


Word— Application's  User  ID  (obtained  at  program  start  time) 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


Memory  Manager  errors 


Returned  unchanged 


C 


extern  pascal  void  ResourceStartUp (userlD) ; 


Word 


userlD; 
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ResourceShutDown  $031E 

Notifies  the  Resource  Manager  that  an  application  is  finished  using  its  own  resource  files. 
The  Resource  Manager  updates,  closes,  and  frees  memory  for  any  open  resource  files. 
Unlike  other  tool  set  shutDown  calls,  the  Resource  Manager  is  still  active  after  this  caO. 
However,  after  calling  ResourceShutDown,  your  application  can  only  access  the  system 
resource  file. 

If  your  application  called  ResourceStartUp,  then  it  must  issue  a  ResourceShutDown 
call  before  quitting. 

Parameters        The  stack  is  not  affected  by  this  call.  There  are  no  input  or  output 


parameters. 


Errors 


None 


C 


extern  pascal  void  ResourceShutDown ()  ; 
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ResourceVersion  $04lE 

Retrieves  the  Resource  Manager  version  number.  Tiie  versionlnfo  result  will  contain  the 
information  in  the  standard  format  defined  in  Appendix  A,  "Writing  Your  Own  Tool  Set," 
in  Volume  2  of  the  Toolbox  Reference. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 
<— SP 


Stack  after  call 


Previous  contents 


versionlnfo 


Word— Resource  Manager  version  number 


<— SP 


Errors 


None 


C 


extern  pascal  Word  ResourceVersion () ; 
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ResourceReset  $051E 

Resets  the  Resource  Manager;  issued  only  when  the  system  is  reset. 

A  Warning     An  application  must  never  make  this  call,  a 

Parameters        The  stack  is  not  affected  by  this  call.  There  are  no  input  our  output 
parameters. 

Errors  None 

C  Call  must  not  be  made  by  an  application. 
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ResourceStatus  $06lE 

Returns  a  flag  indicating  wliether  the  Resource  Manager  is  active.  If  the  Resource  Manager 
loaded  and  initialized  successfully  at  system  startup,  then  this  function  returns  a  value  of 
TRUE.  If  the  Resource  Manager  did  not  successfully  load  or  initialize,  then  the  Tool 
Locator  returns  a  f  uncNotFoundErr  error  code  ($0002). 

♦  Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  ResourceStatus,  your  program  need  only  check 
the  value  of  the  returned  flag.  If  the  Resource  Manager  is  not  active,  the  returned  value 
will  be  FALSE  (NIL). 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


activeFlag 


Word— BOOLEAN;  TRUE  if  Resource  Manager  is  active 


<— SP 


Errors 


$0002 


f uncNotFoundErr 


Resource  Manager  not  active 


C 


extern  pascal  Word  ResourceStatus () ; 
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Resource  Manager  tool  calls 

This  section  discusses  the  Resource  Manager  tool  calls,  in  call  name  order. 


AddResource  $0C1£ 


Adds  a  resource  to  the  current  resource  file.  The  Resource  Manager  marks  the  new  resource 
as  changed  and  will  write  the  new  resource  to  disk  when  the  file  is  updated.  Your  program 
specifies  the  attributes  of  the  new  resource  in  a  flag  word  passed  to  AddResource, 
Some  of  these  attributes  control  how  memory  is  allocated  for  the  new  resource  when  it  is 
loaded  by  an  application,  others  govern  Resource  Manager  processing.  For  more 
information  about  the  various  attributes,  see  "Resource  attributes"  earlier  in  this  chapter. 

Parameters 

Stack  before  call 


Previous  contents 


resourceHandle  - 


resourceAttr 


resourceType 


resourcelD 


Stack  after  call 


Long— Handle  of  resource  in  memory 

Word— Attributes  of  the  resource 
Word— Type  for  resource 

Long— ID  for  resource 

<— SP 


PreiHoiiS  contents 


Errors 


<— SP 

$1E04  resNoCurFile 
$1E05  resDupID 

$1E0E  resDiskFull 
WriteResource  errors 
Memory  Manager  errors 
GS/OS  errors 


There  is  no  current  resource  file 
Another  resource  in  the  current 
file  is  using  this  ID 
Volume  full 
Returned  unchanged 
Returned  unchanged 
Returned  unchanged 
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resourceAttr 

resourceType 
resourcelD 


extern  pascal  void  AddResource (resourceHandle, 

resourceAttr,   resourceType,   resourcelD) ; 


Specifies  the  memory  location  and  size  of  the  resource  to  be  added 
to  the  current  resource  file.  If  the  handle  is  empty,  AddResource 
creates  a  resource  with  zero  length.  Never  pass  a  handle  that  was 
created  by  the  Resource  Manager,  unless  the  resource  in  that  handle 
has  been  detached  (see  DetachResource  tool  call). 

If  resAbsLoad  in  resourceAttr\s  set  to  1,  then  the  Resource  Manager 
obtains  the  size  of  the  resource  from  the  mapsize  field  in  the 
resource  map. 

Bit  flags  defining  the  attributes  of  the  resource  to  be  added.  For 
information  about  the  specific  flags,  see  "Resource  attributes"  eariier 
in  this  chapter. 

Type  of  resource  to  be  added.  See  "Identifying  resources"  earlier  in 
this  chapter  for  details. 

ID  for  new  resource.  Must  be  unique  among  resources  of  the  same 
type.  See  "Identifying  resources"  earlier  in  this  chapter  for  more 
information.  Use  the  uniqueResourceiD  tool  call  to  obtain  a 
unique  ID. 


Long 
Word 


resourceHandle,  resourcelD; 
resourceAttr,  resourceType; 
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CloseResourceFile  $0B1£ 

Updates  a  specified  resource  file,  frees  any  memory  used  by  the  resource  map  for  the  file 
and  any  resources  currently  loaded,  and  closes  the  file.  Your  program  passes  the  file  ID  of 
the  resource  file  to  be  closed.  This  file  ID  is  obtained  from  the  openResourceFiie  tool 
call. 

If  the  file  being  closed  is  the  current  resource  file,  the  next  file  in  the  resource  file  list 
becomes  the  current  resource  file.  Your  program  can  close  the  system  resource  file  by 
passing  the  system  file  ID  ($0001).  Note,  however,  that  some  tool  calls  require  system 
resources  (for  example,  the  system  stores  the  control  definition  procedure  for  icon 
button  controls  in  the  system  resource  file).  These  calls  will  not  work  if  you  close  the 
system  resource  file,  or  set  the  search  depth  so  shallow  that  the  system  resource  file  is 
inaccessible  (see  "setResourceFiieDepth"  later  in  this  chapter). 

♦  Note:  Your  program  does  not  need  to  issue  CloseResourceFile  calls  for  all  open 
resource  files  when  quitting.  The  ResourceShutDown  call  automatically  updates  and 
closes  any  open  resource  files. 

Parameters 

Stack  before  call 

Previous  contents 


fllelD 


Word— ID  of  open  resource  file;  NIL  to  close  all  open  files 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


WriteResource  errors 


GS/OS  errors 


Returned  unchanged 
Returned  unchanged 


C 


extern  pascal  void  CloseResourceFile (filelD) ; 


Word 


filelD; 
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CountResources  $221£ 


Counts  the  number  of  resources  of  a  specified  type  in  all  resource  files  available  to  the 
calling  program  in  its  search  sequence.  Your  program  specifies  the  resource  type  to  be 
counted.  The  Resource  Manager  counts  all  resources  of  that  type  in  open  resource  files 
available  to  your  program,  including  the  system  resource  file. 

♦  Note:  This  call  can  be  very  slow  when  you  have  many  resources  or  resource  files.  Do  not 
issue  this  call  in  time-critical  procedures. 

Parameters 

Stack  before  call 

Previous  contents 


resourceType 


Space 


Long— Space  for  result 

Word— Resource  type  to  be  counted 


<— SP 


Stack  after  call 


Previous  contents 


-  totalResources  - 


Long— Number  of  resources  of  specified  type 


<— SP 


Errors 


None 


C 


extern  pascal  Long  CountResources (resourceType) ; 


Word 


resourceType ; 
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CountTypes  $201E 

Counts  the  number  of  different  resource  types  in  all  resource  files  available  to  the  calling 
program  in  its  search  sequence,  including  the  system  resource  file. 

♦  Note:  This  call  can  be  very  slow  when  you  have  many  resources  or  resource  files.  Do  not 
issue  this  call  in  time-critical  procedures. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


totalTypes 


Word— Number  of  different  resource  types 


<— SP 


Errors 


Memory  Manager  errors 


Returned  unchanged 


C 


extern  pascal  Word  CountTypes () ; 
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CreateResourceFile  $091E 

Initializes  a  resource  fork  with  no  resources.  If  necessary,  CreateResourceFile  will 
create  the  file  to  contain  the  resource  fork.  The  specific  actions  performed  by  this  call 
depend  upon  the  state  of  the  specified  input  file; 

No  file  of  specified  name  Create  file  with  specified  auxType,  fileType, 

fileAccessJileName.  Create  and  initialize 
resource  fork 

File  with  no  resource  fork  Create  and  initialize  resource  fork 

File  with  empty  resource  fork  Initialize  resource  fork 

File  with  non-empty  resource  fork         Return  resForkused  error 

Parameters 

Stack  before  call 


Previous  contents 


auxType 


fileType 


fileAccess 


fileName 


Stack  after  call 


Long— GS/OS  auxiliary  file  type  (used  only  if  file  does  not  exist) 

Word—GS/OS  file  type  (used  only  if  file  does  not  exist) 
Word— GS/OS  file  access  (used  only  if  fOe  does  not  exist) 

Long— Pointer  to  GS/OS  class  1  input  pathname  for  resource  file 

<— SP 


Previous  contents 


Errors 


<— SP 

$1E01  resForkUsed 
GS/OS  errors 


Resource  fork  for  specified  file  is 
not  empty 
Returned  unchanged 


extern  pascal  void  CreateResourceFile (auxType, 
fileType,   fileAccess,   fileName) ; 

Long  auxType,  fileName; 

Word  fileType,  fileAccess; 
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DetachResource  $181£ 

Instmcts  the  Resource  Manager  to  dispose  of  its  control  blocks  for  a  specified  resource. 
The  resource  itself  remains  in  memory;  the  calling  program  is  responsible  for  freeing  its 
handle.  The  resource  to  be  detached  must  be  marked  as  unchanged. 

This  call  can  be  used  to  copy  resources  between  different  resource  files.  After  issuing  the 
DetachResource,  add  the  resource  to  the  new  resource  file  by  calling  AddResource. 
After  issuing  the  AddResource  call,  the  Resource  Manager  is  again  responsible  for  the 
resource  handle. 

Parameters 

Stack  before  call 


Previous  contents 


resourceType 


resourcelD 


Word— Type  of  resource  to  be  detached 
Long— ID  of  resource  to  be  detached 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

$1E06  resNotFound 
$1E0C  resHasChanged 


Specified  resource  cannot  be 
found 

Resource  has  been  changed  and 
has  not  been  updated 


extern  pascal  void  DetachResource (resourceType, 
resourcelD) ; 


Word  resourceType; 
Long  resourcelD; 
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GetCurResourceApp  $141E 

Returns  the  User  ID  for  the  application  that  is  currently  using  the  Resource  Manager.  If  the 
Resource  Manager  is  not  in  use,  this  call  returns  the  Resource  Manager's  User  ID  ($401E). 
This  call  is  used  by  desk  accessories  and  application  switchers  (see  "Application  switchers 
and  desk  accessories"  earlier  in  this  chapter  for  more  information). 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


userlD 


Word— User  ID  of  current  application;  $401E  if  none 


<— SP 


Errors 


None 


C 


extern  pascal  Word  GetCurResourceApp () ; 
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GetCurResourceFile  $121£ 

Returns  the  file  ID  of  the  current  resource  file.  This  call  returns  a  NIL  value  if  there  is  no 
current  file. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Stack  after  call 


Word— Space  for  result 
<— SP 


Previous  contents 


filelD 


Errors 
C 


$1E04 


Word— File  ID  of  current  resource  file;  NIL  if  none 
<— SP 


resNoCurFile 


No  current 'resource  file 


extern  pascal  Word  GetCurResourceFile () ; 
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GetlndResource  $231£ 

Finds  a  resource  of  a  specified  type  by  means  of  its  index,  and  returns  tiie  resource  ID  for 
that  resource.  The  index  value  corresponds  to  the  position  of  the  desired  resource  among 
all  resources  of  the  specified  type  in  all  resource  files  available  to  the  calling  program  in  its 
search  sequence;  the  first  resource  is  number  1. 

Use  this  call  to  find  every  resource  of  a  given  type  by  repeatedly  issuing  the  call, 
incrementing  the  index  value  until  the  call  returns  resIndexRange. 

♦  Note:  This  call  can  be  very  slow  when  you  have  many  resources  or  resource  files.  Do  not 
issue  this  call  in  time-critical  procedures. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


resourceType 


resourcelndex  - 


Stack  after  call 


Long — Space  for  result 
Word— Type  of  resource  to  find 
Long— Index  of  resource  to  find 
<— SP 


Previous  contents 


resourcelD 


Errors 


Long— ID  of  resource  matching  type  and  index 
<— SP 

$1E0A  resIndexRange 
Memory  Manager  errors 


Index  is  out  of  range  (no  resource 
found) 

Returned  unchanged 
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C  extern  pascal  Long  GetlndResource (resourceType, 

resourcelndex) ; 

Word  resourceType; 
Long  resourcelndex 
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GetlndType  $211E 

Finds  a  resource  type  value  by  means  of  its  index.  The  index  value  corresponds  to  the 
1-relative  position  of  the  desired  resource  type  among  all  types  in  all  resource  files 
available  to  the  calling  program  in  its  search  sequence. 

Use  this  call  to  find  every  resource  type  in  all  files  available  to  an  application  by  repeatedly 
issuing  the  call,  incrementing  the  index  value  until  the  call  returns  resIndexRange. 

♦  Note:  This  call  can  be  very  slow  when  you  have  many  resources  or  resource  files.  Do  not 
issue  this  call  in  time-critical  procedures. 

Parameters 

Stack  before  call 

Previous  contents 


typelndex 


Space 


Word— Space  for  result 
Word— Index  of  type  to  find 


<— SP 


Stack  after  call 


Previous  contents 


resourceType 


Word— Type  matching  index 


<— SP 


Errors 


Memory  Manager  errors 


$1E0A 


r e  s I ndexRa nge 


Index  is  out  of  range  (no  more 
types) 

Returned  unchanged 


C 


extern  pascal  Word  GetlndType (typelndex) ; 


Word 


typelndex; 
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GetMapHandle  $26l£ 

Returns  a  handle  to  the  resource  map  for  a  specified  resource  file.  Your  program  specifies 
the  desired  resource  file  by  passing  its  file  ID  to  GetMapHandle.  This  call  searches  all 
open  resource  files,  irrespective  of  the  search  sequence  in  effect. 

For  information  on  the  format  and  content  of  resource  file  maps,  see  "Resource  file 
format"  earlier  in  this  chapter. 

♦  Note:  This  call  provides  greater  application  flexibility;  however,  most  applications  will 
not  need  to  issue  this  call. 

Parameters 

Stack  before  call 

Pretnous  contents 


Space 


Long— Space  for  result 


filelD 


Word— ID  of  resource  file  to  find 


<— SP 


Stack  after  call 


Previous  contents 


-    mapHandle  - 


Long— Handle  of  resource  file  map;  NIL  if  none  found 


<— SP 


Errors 


$1E07 


resFileNotFound 


Specified  file  ID  does  not  match 
an  open  file 


C 


extern  pascal  Long  GetMapHandle (filelD) ; 


Word 


filelD; 
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filelD  Specifies  the  resource  file  whose  map  is  to  be  returned.  This  value  is 

obtained  from  the  OpenResourceFile  tool  call.  Typically,  your 
program  sets  this  parameter  with  the  file  ID  for  a  particular  resource 
file.  However,  this  field  also  supports  the  following  special  values: 

NIL  returns  handle  to  map  for  current  resource  file 

$FFFF  returns  handle  to  map  for  system  resource  file 
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GetOpenFileRefNum  $1F1£ 

Returns  the  GS/OS  file  reference  number  (ref  Num)  associated  with  the  resource  fork  of 
an  open  resource  file.  Your  program  specifies  the  resource  file  by  means  of  its  file  ID.  The 
Resource  Manager  searches  all  open  resource  files  for  a  file  with  a  matching  ID. 

Your  program  may  use  this  reference  number  to  read  data  from  the  resource  file.  However, 
your  program  should  very  careful  to  maintain  the  structure  of  the  fork  during  write 
operations;  careless  writing  could  destroy  the  resource  fork.  Further,  your  program  should 
never  directly  close  the  file  using  the  reference  number.  Only  the  Resource  Manager  should 
close  files  it  has  opened. 

For  information  on  the  format  and  content  of  resource  file  maps,  see  "Resource  file 
format"  earlier  in  this  chapter. 

♦  Note:  This  call  provides  greater  application  flexibility;  however,  most  applications  will 
not  need  to  issue  this  call. 

Parameters 

Stack  before  call 

Previous  contents 


filelD 


Space 


Word— Space  for  result 
Word— ID  of  resource  file  to  find 


<— SP 


Stack  after  call 


Previous  contents 


openReJNum 


Word — GS/OS  file  reference  number 


<— SP 


Errors 


$1E07 


resFileNotFound 


Specified  file  ID  does  not  match 
an  open  file 


C 


extern  pascal  Word  GetOpenFileRefNum (filelD) ; 


Word 


filelD; 
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filelD  Specifies  the  resource  file  whose  reference  number  is  to  be  returned. 

This  value  is  obtained  from  the  openResourceFiie  tool  call, 
Typially,  your  program  sets  this  parameter  with  the  file  ID  for  a 
particular  resource  file.  However,  this  field  also  supports  the  following 
special  values: 

NIL  returns  reference  number  for  current  resource  file 

$FFFF  returns  reference  number  for  system  resource  file 
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GetResourceAttr  $1B1£ 

Returns  the  attribute  flag  word  for  a  specified  resource.  Your  program  specifies  the  type 
and  ID  for  the  desired  resource.  For  more  information  about  the  format  and  content  of 
the  attribute  word,  see  "Resource  attributes"  earlier  in  this  chapter. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


resourceType 


resourcelD 


Stack  after  call 


Word— Space  for  result 
Word— Type  of  resource  to  find 

Long— ID  of  resource  to  find 

<— SP 


Previous  contents 


resourceAttr 


Errors 
C 


$1E06 


Word— Attribute  word  for  specified  resource 
<— SP 


resNotFound 


Specified  resource  not  found 


extern  pascal  Word  GetResourceAttr (resourceType, 
resourcelD) ; 

Word  resourceType; 
Long  resourcelD; 
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GetResourceSize  $1D1£ 

Returns  the  size  of  the  specified  resource.  Your  program  specifies  the  type  and  ID  for  the 
desired  resource.  Resource  size  is  defined  as  the  number  of  bytes  the  resource  occupies  in 
the  resource  fork  on  dislc. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


resourceType 


resourcelD 


Stack  after  call 


Long— Space  for  result 
Word— Type  of  resource  to  find 
Long— ID  of  resource  to  find 
<— SP 


Previous  contents 


-  resourceSize 


Errors 
C 


$1E06 


Long— Size  of  specified  resource 
<— SP 

Specified  resource  not  found 


resNotFound 


extern  pascal  Long  GetResourceSize (resourceType, 
resourcelD) ; 

Word  resourceType; 
Long  resourcelD; 
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HomeResourceFile  $151E 

Returns  the  file  ID  of  the  resource  file  that  contains  a  specified  resource.  Your  program 
specifies  the  type  and  E)  for  the  resource  in  question, 

♦  Note:  If  multiple  resources  share  the  specified  type  and  ID  values,  and  your  program 
has  changed  the  resource  search  sequence  (with  the  setCurResourceFiie  tool 
call),  this  call  may  return  a  different  result  than  on  previous  calls. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


resourceType 


resourcelD 


Word— Space  for  result 
Word— Type  of  resource  to  find 

Long— ID  of  resource  to  find 

<— SP 


Stack  after  call 


Previous  contents 


fllelD 


Errors 
C 


$1E06 


Word— File  ID  for  home  resource  file  for  resource;  NIL  if  not  found 
<— SP 

resNotFound  Specified  resource  not  found 


extern  pascal  Word  HomeResourceFile (resourceType, 
resourcelD) ; 

Word  resourceType; 
Long  resourcelD; 


45-52    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


LoadAbsResource  $271£ 

Loads  a  resource  into  a  specified  absolute  memory  location.  Your  program  specifies  the 
type  and  ID  of  the  resource  to  load,  the  memory  location  into  which  the  Resource 
Manager  is  to  load  the  resource,  and  the  maximum  number  of  bytes  to  load.  Note  that  the 
resAbsLoad  flag  in  the  Attributes  word  for  the  desired  resource  must  be  set  to  1. 


♦  Note:  This  call  does  not  respect  the  disk  load  setting  maintained  by  the 
SetResourceLoad  tOOl  call. 


A  Warning      Most  applications  will  not  have  to  issue  this  call.  In 
order  to  use  this  call  you  must  have  a  thorough 
understanding  of  using  absolute  memory,  Issuing  this 
call  with  an  incorrectly  set  loadAddress  parameter  will 
corrupt  system  memory.  ▲ 


Parameters 

Stack  before  call 


Previous  contents 


Space 


-    loadAddress  - 


maxSize 


resourceType 


resourcelD 


Stack  after  call 


Long— Space  for  result 

Long— Address  at  which  to  load  resource 

Long— Maximum  number  of  bytes  to  load 

Word— Type  of  resource  to  find 

Long— ID  of  resource  to  find 

<— SP 


Previous  contents 


-    resourceSize  - 


Long— Size  of  resource  on  disk 
<— SP 
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Errors 


loadAddress 


$1E03 


resNoConverter 


$1E06  resNotFound 
GS/OS  errors 


No  converter  routine  to  load 
resource 

Specified  resource  not  found 
Returned  unchanged 


extern  pascal  Long  LoadAbsResource (loadAddress, 
maxSize,   resourceType,   resourcelD) ; 

Word  resourceType; 

Long  loadAddress,  maxSize,  resourcelD; 

Specifies  the  memory  location  at  which  the  Resource  Manager  is  to 
load  the  resource.  If  your  program  passes  a  NIL  value,  the  Resource 
Manager  uses  the  address  stored  in  the  resHandie  field  of  the 
appropriate  entry  in  the  resource  index. 
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LoadResource  $0£1£ 

Loads  a  resource  into  memory  and  returns  a  handle  to  that  location.  Your  program 
specifies  the  type  and  ID  of  the  resource  to  load.  The  returned  handle  provides 
addressability  to  the  resource. 

The  LoadResource  call  searches  both  memory  and  disk  for  the  specified  resource.  If  the 
resource  is  already  in  memory,  LoadResource  returns  a  handle  to  that  memory  location. 
If  the  resource  has  been  purged  from  memory,  LoadResource  reloads  the  resource  and 
returns  its  handle.  If  the  resource  has  not  been  loaded,  LoadResource  allocates  a  handle, 
loads  the  resource,  and  retums  the  handle  to  your  program. 

Your  program  may  manipulate  the  resource  while  it  is  in  memory,  and  may  even  change  the 
size  of  the  resource  (to  any  size  other  than  zero  bytes).  If  you  want  the  changes  to  be 
reflected  in  the  resource  file,  use  the  MarkResourceChange  tool  call  to  set  on  the 
changed  attribute  for  the  file.  The  Resource  Manager  will  then  write  the  changed  resource 
to  disk  the  next  time  the  resource  file  is  updated.  Your  program  can  force  the  Resource 
Manager  to  write  the  resource  to  disk  immediately  by  issuing  either  the  writeResource 
or  the  UpdateResourceFile  tOOl  call. 

Note  that  your  program  should  not  dispose  of  the  handle;  only  the  Resource  Manager 
should  free  the  memory  that  it  allocates. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


resourceType 


resourceE) 


Stack  after  call 

Previous  contents 


-  resourceHandle  - 


Long — Space  for  result 
Word— Type  of  resource  to  find 
Long— ID  of  resource  to  find 
<— SP 


Long— Handle  of  resource  in  memory 
<— SP 
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Errors  $1E03      resNoConverter  No  converter  routine  to  load 

resource 

$1E06      resNotFound  Specified  resource  not  found 

GS/OS  errors  Returned  unchanged 

Memory  Manager  errors  Returned  unchanged 

C  extern  pascal  Long  LoadResource (resourceType, 

resourcelD) ; 

Word  resourceType; 
Long  resourcelD; 
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MarkResourceChange  $101E 

Instructs  the  Resource  Manager  to  write  the  specified  resource  to  disk  the  next  time  its 
resource  file  is  updated.  Your  program  specifies  the  type  and  ID  of  the  resource  to  be 
marked  as  changed. 

Use  this  call  when  you  want  in-memory  changes  to  a  resource  to  be  permanent. 

Parameters 

Stack  before  call 

Previous  contents 

changeFlag  Word— BOOLEAN;  TRUE  for  changed,  FALSE  for  not  changed 
resourceType  Word— Type  of  resource  to  find 

resourcelD    -  Long— ID  of  resource  to  find 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


$1E06 


resNotFound 


Specified  resource  not  found 


C 


extern  pascal  void  MarkResourceChange (changeFlag, 
resourceType,   resourcelD) ; 


Word 


Long 


changeFlag,  resourceType; 
resourcelD; 


Chapter  45  Resource  Manager  45-57 


Apple  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


MatchResourceHandle  $1E1E 

Returns  the  type  and  ID  of  a  resource,  given  a  handle  to  that  resource.  The  Resource 
Manager  searches  all  open  resource  files  for  a  match,  without  regard  for  the  search 
sequence  in  effect. 


♦  Note:  The  Resource  Manager  has  been  optimized  to  access  resources  by  type  and  ID, 
irrespective  of  the  number  of  resources  in  the  system.  While 
MatchResourceHandle  works  well  with  relatively  small  numbers  of  resources  (less 
than  100),  for  files  with  large  numbers  of  resources  this  call  can  be  very  slow.  In  order 
to  avoid  this  overhead,  consider  storing  the  resource  type  and  ID  in  the  resource 
structure,  so  that  your  program  can  directly  access  this  information. 


Parameters 

Stack  before  call 


Previous  contents 


foundRec 


-  resourceHandle 


Stack  after  call 


Long— Pointer  to  location  in  which  to  return  type  and  ID 

Long— handle  of  resource 
<— SP 


Previous  contents 


Errors 
C 


$1E06 


<— SP 
resNotFound 


Specified  resource  not  found 


extern  pascal  void  MatchResourceHandle (foundRec, 
resourceHandle) ; 

Pointer  foundRec; 

Long  resourceHandle; 
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foundRec  Must  point  to  a  location  in  memory  that  can  accept  6  bytes  of  data; 

the  type  and  ID  of  the  resource  in  question.  On  successful  return  from 
MatchResourceHandie,  that  location  will  contain  the  following 
data: 


$00 

resourceType 

$02 

resourcelD 

Word— Type  of  resource 


Long— ID  of  resource 
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OpenResourceFile  $0A1E 

Opens  a  specified  resource  file,  making  it  the  current  file,  and  returns  a  unique  file  ID  to 
the  calling  program.  Your  program  specifies  the  class  1  GS/OS  pathname  to  the  desired 
resource  file.  The  Resource  Manager  loads  the  resource  map  into  memory,  along  with  any 
resources  marked  to  be  pre-loaded  (resPreLoad  flag  is  set  to  1  in  the  Attributes  word 
for  the  resource). 

Parameters 

Stack  before  call 


Previous  contents 


Space 


openAccess 


-  mapAddress 


filename 


Word— Space  for  result 
Word— File  access 

Long— Address  of  resource  map  in  memory 

Long— Pointer  to  GS/OS  class  1  pathname  for  resource  file 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


filelD 


$1E06 
$1E09 
$1E0B 


Word— ID  of  open  resource  file 
<— SP 


resNotFound 

resNoUniquelD 

resSysIsOpen 


GS/OS  errors 
Memory  Manager  errors 


Specified  resource  not  found 
Too  many  resource  files  open 
System  resource  file  is  already 
open 

Returned  unchanged  (EOF  if 
empty  fork) 
Returned  unchanged 


extern  pascal  Word  OpenResourceFile (openAccess, 
mapAddress,   fileName) ; 

Word  openAccess; 

Pointer      mapAddress,  fileName; 
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openAccess         Contains  GS/OS  file  access  privileges  for  the  resource  file.  See  the 
GS/OS  Reference  for  more  information. 

mapAddress  To  open  a  resource  file  on  disk,  set  this  field  to  NIL.  If  the  map  is  in 
memory,  load  this  field  with  a  pointer  to  that  map.  In  this  case,  the 
Resource  Manager  opens  the  file  that  is  already  in  memory. 
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ReleaseResource  $171£ 

Sets  the  purge  level  of  the  memory  used  by  a  resource.  Your  program  specifies  the  type 
and  ID  of  the  resource  whose  memory  is  to  be  freed,  and  the  purge  level  to  be  assigned  to 
the  memory.  See  Chapter  12,  "Memory  Manager,"  in  Volume  1  of  the  Toolbox  Reference  for 
more  information  about  purge  levels  and  memory  management.  Note  that  this  call  does 
not  unlock  the  handle. 

Parameters 

Stack  before  call 

Previous  contents 

purgeLevel  Word— Purge  level  for  memory 
resourceType  Word— Type  of  resource  to  find 

resourcelD    -  Long— ID  of  resource  to  find 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


$1E06 
$1E0C 


resHasChanged 


resNotFound 


Specified  resource  not  found 
Resource  has  been  changed  but 
not  updated 


C 


extern  pascal  void  ReleaseResource (purgeLevel, 
resourceType,   resourcelD) ; 


Word 


purgeLevel,  resourceType; 
resourcelD; 


Long 


purgeLevel 


Specifies  the  Memory  Manager  purge  level  to  be  assigned  to  the  freed 
memory.  Valid  Memory  Manager  purge  levels  lie  in  the  range  of  0  to  3. 
In  order  to  direct  the  Resource  Manager  to  immediately  dispose  of 
the  handle,  set  this  field  to  a  negative  value. 
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RemoveResource  $0F1E 

Deletes  a  resource  from  its  resource  file  and  releases  any  memory  used  by  the  resource. 
Your  program  specifies  the  type  and  ID  of  the  resource  to  be  deleted.  After  successful 
return  from  this  call,  the  specified  resource  is  no  longer  available  for  access  or  loading. 

Parameters 

Stack  before  call 


Previous  contents 


resourceType 


resourcelD 


Word— Type  of  resource  to  find 
Long— ID  of  resource  to  find 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1E06 
$1E0E 


<— SP 

resNotFound 
resDiskFull 


Specified  resource  not  found 
Volume  full 


extern  pascal  void  RemoveResource (resourceType, 
resourcelD) ; 


Word  resourceType; 
Long  resourcelD; 
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ResourceConverter  $281E 

Installs  or  removes  a  converter  routine  from  either  the  application  or  system  converter  list. 
Your  program  specifies  the  address  of  the  converter  routine,  the  type  of  resource  the 
routine  acts  on,  and  flags  indicating  the  type  of  operation  to  perform  and  the  list  to 
modify.  For  background  information  on  resource  converter  routines,  see  "Resource 
converter  routines"  earlier  in  this  chapter. 

The  Resource  Manager  maintains  two  classes  of  converter  routine  lists:  one  for  your 
application  and  one  for  the  system.  Each  application  has  its  own  converter  routine  list.  All 
programs  share  access  to  the  system  list.  When  the  Resource  Manager  searches  for  a 
routine  to  convert  a  resource  of  a  given  type,  it  first  searches  the  application  list  for  the 
calling  program,  then  the  system  list.  As  a  result,  your  program  can  override  converter 
routines  in  the  system  list  by  installing  a  routine  for  the  same  resource  type  in  its 
application  list.  Applications  must  never  log  routines  into  or  out  of  the  system  converter 
list. 

An  application  can  log  in  up  to  10,922  converter  routines.  Note,  however,  that  the 
Resource  Manager  does  not  check  for  this  limit.  The  same  converter  routine  can  be  logged 
in  for  more  than  one  resource  type. 

The  system  contains  a  standard  routine  to  convert  code  resources.  Use  the 
GetcodeResConverter  Miscellaneous  Tool  Set  tool  call  to  obtain  the  address  of  that 
routine  (see  Chapter  39,  "Miscellaneous  Tool  Set  Update,"  in  this  book  for  details  on  the 
GetcodeResConverter  call). 

Parameters 

Stack  before  call 


Previous  contents 

converter     -  Long— Pointer  to  converter  routine 
resourceType  Word— Type  of  resource  acted  on  by  the  routine 
logFlags  Word— Flag  governing  action  and  list  to  access 
<— SP 

Stack  after  call 


Previous  contents 


<— SP 
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Errors 


$1E0D 


resDiff Converter 


logFlags 
Reserved 

list 
action 


Memory  Manager  errors 


Another  converter  already  logged 
in  for  this  resource  type 
Returned  unchanged 


extern  pascal  void  ResourceConverter (converter, 
resourceType,  logFlags) ; 

Pointer  converter; 

Word  resourceType,  logFlags; 

Specifies  whether  to  log  the  converter  routine  into  or  out  of  its  list. 
Also  specifies  which  list  (application  or  system)  to  access: 


Bits  2-15 
Bit  1 


Bit  0 


Must  be  set  to  0 

Indicates  which  routine  list  to  access: 
1  -  System  converter  list 

0  -  Application  converter  list 
Specifies  action  to  take: 

1  -  Log  routine  into  list 

0  -  Log  routine  out  of  list 
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SetCurResourceApp  $131E 

Tells  the  Resource  Manager  that  another  application  will  now  be  issuing  Resource  Manager 
calls.  This  call  is  used  by  desk  accessories  and  application  switchers  (see  "Application 
switchers  and  desk  accessories"  earlier  in  this  chapter  for  more  information).  Before 
issuing  this  call,  your  program  must  have  registered  itself  with  the  Resource  Manager  by 
calling  ResourceStartUp. 

Parameters 

Stack  before  call 

Previous  contents 


userlD 


Word— User  ID  of  application  that  will  be  using  Resource  Manager 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


$1E08 


resBadAppID 


User  ID  unknown  to  Resource 
Manager  (has  not  called 
ResourceStartUp) 


C 


extern  pascal  void  SetCurResourceApp (userlD) ; 


Word 


userlD; 
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SetCurResourceFile  $111E 

Makes  a  specified  resource  file  the  current  file.  The  Resource  Manager  searches  typically 
start  with  the  current  resource  file,  so  by  specifying  a  particular  file  as  the  current  file,  your 
program  can  control  the  file  search  sequence.  For  more  information  about  Resource 
Manager  search  processing,  see  "Using  resources"  earlier  in  this  chapter. 

Parameters 

Stack  before  call 

Previous  contents 


filelD 


Word— File  ID  of  resource  file  to  be  made  current  file 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


$1E07 


resFileNotFound 


Specified  resource  file  not  found 


C 


extern  pascal  void  SetCurResourceFile (filelD) ; 


Word 


filelD; 
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SetResourceAttr  $1C1E 

Sets  the  attributes  for  a  resource.  Your  program  specifies  the  type  and  ID  for  the  desired 
resource  and  a  new  attribute  word  for  the  resource.  The  Resource  Manager  replaces  the 
existing  attribute  word  for  the  resource  with  the  one  provided  to  this  call.  For  more 
information  about  the  format  and  content  of  the  attribute  word,  see  "Resource 
attributes"  eariier  in  this  chapter. 

If  your  program  changes  the  attributes  of  a  resource,  it  should  not  also  mark  the  resource 
as  changed.  The  Resource  Manager  automatically  tracks  these  changes. 

Note  that  these  changes  only  affect  future  use  of  the  resource.  For  example,  if  your 
program  changes  the  attributes  for  a  resource  to  indicate  that  it  should  be  locked  into 
memory  (sets  attrLocked  flag  to  1),  that  action  does  not  change  the  status  of  any 
current  instances  of  that  resource  in  memory.  However,  the  next  time  the  Resource 
Manager  allocates  a  handle  for  the  resource,  the  memory  for  that  new  handle  will  be 
locked. 

Parameters 

Stack  before  call 

Previous  contents 

resourceAttr  Word— New  attribute  flag  word  for  resource 

resourceType  Word— Type  of  resource  to  find 

resourcelD    -  Long— ID  of  resource  to  find 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


$1E06 


resNotFound 


Specified  resource  not  found 


C 


extern  pascal  void  SetResourceAttr (resourceAttr, 
resourceType,   resourcelD) ; 


Word 


Long 


resourceAttr,  resourceType; 
resourcelD; 
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SetResourceFileDepth  $251E 

Sets  the  number  of  files  Resource  Manager  is  to  search  during  a  search  operation,  and 
returns  the  previous  search  depth  setting.  For  more  information  about  the  Resource 
Manager's  search  sequence,  see  "Resource  file  search  sequence"  earlier  in  this  chapter. 

Parameters 


Stack  before  call 


Previous  contents 


Space 


searchDepth 


Word— Space  for  result 

Word — Number  of  files  to  search 

<— SP 


Stack  after  call 


PreiHous  contents 


originalDepth 


Errors 
C 


searchDepth 


Word— Search  file  depth  before  call 
<— SP 


None 


extern  pascal  Word 

SetResourceFileDepth (searchDepth) ; 


Word 


searchDepth; 


Specifies  the  number  of  files  to  search.  SetResourceFileDepth 

accepts  the  following  special  values: 

NIL  Return  current  search  depth  without  changing  it 

$FFFF         Search  all  files 
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SetResourcelD  $1A1E 

Changes  the  ID  for  a  resource  to  a  new  value.  Your  program  specifies  the  type  and  current 
ID  for  the  resource  to  be  changed. 

If  your  program  changes  the  ID  value  for  a  resource,  it  should  not  mark  the  resource  as 
changed.  The  Resource  Manager  automatically  tracks  these  changes. 

Parameters 

Stack  before  call 


Previous  contents 


netvID 


resourceType 


currentID 


Stack  after  call 


Long— New  ID  for  resource 
Word— Type  of  resource  to  find 
Long— Current  ID  of  resource  to  find 
<— SP 


Previous  contents 


Errors 


$1E05 
$1E06 


<— SP 
resDupID 

resNotFound 


Specified  new  ID  already 
in  use  for  this  type 
Specified  resource  not  found 


extern  pascal  void  SetResourcelD (newID, 
resourceType,   currentID) ; 

Long  newID,  current  ID; 

Word  resourceType; 
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SetResourceLoad  $24lE 

Controls  Resource  Manager  access  to  disk  when  loading  resources.  If  you  disable  disk 
loading,  the  Resource  Manager  will  not  load  resources  from  disk,  but  will  allocate  empty 
handles  for  requested  resources.  However,  if  a  resource  had  been  loaded  into  memory 
prior  to  disk  loading  being  disabled,  the  Resource  Manager  will  return  a  valid  handle.  For 
example,  a  LoadResource  tool  call  will  return  an  empty  handle  if  loading  is  set  to  FALSE 
and  the  resource  has  not  been  loaded  into  memory  previously. 


♦  Note:  Most  applications  will  not  issue  this  call. 


Parameters 

Stack  before  call 


Previous  contents 


Space 


readFlag 


Stack  after  call 


Word— Space  for  result 

Word— Flag  controlling  Resource  Manager  disk  access 
<— SP 


Previous  contents 


originalFlag 


Errors 
C 

readFlag 


Word— Flag  setting  prior  to  call 
<— SP 

None 

extern  pascal  Word  SetResourceLoad (readFlag) ; 


Word 


readFlag; 


Specifies  the  new  setting  for  the  read  flag.  This  call  also  supports  a 
special  value  that  just  returns  the  current  flag  setting: 


0 
1 

Negative 


Do  not  read  resources  from  disk 

Read  resources  from  disk,  if  necessary 

Return  current  setting  only— no  change  to  current 

setting 
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originalFlag        Contains  the  previous  flag  setting: 


0  Do  not  read  resources  from  disk 

1  Read  resources  from  disk,  if  necessary 
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UniqueResourcelD  $191E 

Returns  a  unique  resource  ID  for  a  specified  resource  type.  Your  program  specifies  the 
resource  type  for  the  ID,  and  may  optionally  constrain  the  new  ID  to  a  defined  range.  The 
Resource  Manager  allocates  the  new  ID,  guaranteeing  that  it  is  not  used  by  any  of  your 
program's  currently  available  resources. 

Parameters 


Stack  before  call 


Previous  contents 


Space 


IDRange 


resourceType 


Long— Space  for  result 

Word— Range  of  ID;  $FFFF  for  any  valid  ID  value 
Word— Type  of  resource 
<— SP 


Stack  after  call 


Previous  contents 


resourcelD 


Errors 


IDRange 


Long— Unique  resource  ID 
<— SP 


$1E04  resNoCurFile 
$1E09  resNoUniquelD 


There  is  no  current  resource  file 
No  unique  ID  found 


extern  pascal  Long  UniqueResourcelD (IDRange, 
resourceType) ; 


Word 


IDRange,  resourceType; 


Specifies  a  65,535  element  range  within  which  Resource  Manager  is  to 
allocate  the  new  resource  ID.  The  value  of  IDRange  becomes  the  high- 
order  word  of  the  new  ID.  The  Resource  Manager  then  allocates  a 
unique  ID  from  the  65,535  possible  remaining  values. 
UniqueResourcelD  provides  this  facility  SO  that  application 
programs  can  manage  logial  groups  of  resources,  differentiated  by  ID 
number  ranges. 
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IDRange 


Resource  IDs  in  the  $07FF  range  are  reserved  for  system  use.  Ranges 
from  $0800  through  $FFFE  are  invalid.  The  following  table  summarizes 
the  valid  values  for  IDRange: 


Lowest  possible  ID  returned 


Highest  possible  ID  returned 


$0000 
$0001 
$0002 


$00000001  (ML  is  invalid)  $0000FFFF 
$00010000  $0001FFFF 
$00020000  $0002FFFF 


(and  so  on) 


$07FE  $07FE0000  $07FEFFFF 

$07FF  Reserved  for  system  use 

$0800-$FFFE     Invalid  range  values 

$FFFF  $00000001  $07FEFFFF 

(directs  Resource  Manager  to  allocate  from  any  application  range) 
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UpdateResourceFile  $0D1E 

Applies  any  modifications  that  have  been  made  to  resources  in  memory  to  their  resource 
file,  thus  making  those  changes  permanent.  Your  program  specifies  the  file  ID  of  the 
resource  file  to  be  updated.  The  Resource  Manager  then  locates  and  updates  all  resources 
for  that  file.  If  necessary,  UpdateResourceFile  will  write  the  resource  map  to  disk. 


♦  Note:  Most  applications  will  not  issue  this  call  because  the  ResourceShutDown  tool 
call  automatically  updates  all  resources  opened  by  a  program. 


Parameters 

Stack  before  call 


Previous  contents 


filelD 


Word— ID  of  open  resource  file 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

resNoConverter 

resFileNotFound 
resDiskFull 


$1E03 
$1E07 
$1E0E 

GS/OS  errors 

extern  pascal  void  UpdateResourceFile (filelD) ; 
Word  filelD; 


No  converter  routine  found  for 
resource  type 

No  resource  file  found  with 
specified  file  ID 
Volume  full 
Returned  unchanged 
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WriteResource  $l6lE 

Directs  the  Resource  Manager  to  write  a  modified  resource  to  its  resource  file.  Your 
program  specifies  the  type  and  ID  of  the  resource.  If  that  resource  has  been  modified 
(reschanged  flag  set  to  1  in  the  Attributes  flag  word),  the  Resource  Manager  writes  the 
resource  to  its  resource  file  on  disk.  A  resource  is  marked  changed  as  a  result  of 
AddResource,  MarkResourceChange,  or  SetResourceAttr  (with  resChanged 

set  to  1)  tool  calls. 

♦  Note:  Most  applications  will  not  issue  this  call  because  the  ResourceShutDown  and 
cioseResourceFiie  tool  calls  automatically  write  all  changed  resources  to  the 
appropriate  resource  file  (unless  the  resource  is  write-protected). 

Parameters 

Stack  before  call 

Previous  contents 
resourceType  Word— Type  of  resource  to  write 
resourcelD    -  Long— ID  of  resource  to  write 

<— SP 

Stack  after  call 


Previous  contents 


Errors 


$1E03 

$1E06 
$1E0E 
GS/OS  errors 


<— SP 
resNoConverter 


resNotFound 
resDiskFull 


No  converter  routine  found  for 
resource  type 
Resource  not  found 
Volume  full 
Returned  unchanged 


extern  pascal  void  WriteResource (resourceType, 
resourcelD) ; 

Word  resourceType; 
Long  resourcelD; 
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Resource  Manager  summary 

This  section  briefly  summarizes  the  constants,  data  stmctures,  and  error  codes  used  by 
the  Resource  Manager. 


Table  45-1      Resource  Manager  constants 


Name 


Value  Description 


mapFlag  values 

mapChanged  $0002 

resAttr  flag  values 

resChanged  $0020 

resPreLoad  $0040 

resProtected  $0080 

resAbsLoad  $0400 

resConverter  $0800 

resMemAttr  $C31C 

System  file  ID 

sysFilelD  $0001 


Set  to  1  if  the  map  has  changed  and  must  be  written 
to  disk 


Set  to  1  if  the  resource  has  changed  and  must  be 
written  to  disk 

Set  to  1  if  the  resource  should  be  loaded  into  memory 

by  OpenResourceFile 

Set  to  1  if  the  resource  should  never  be  written  to 

disk 

Set  to  1  if  the  resource  should  be  loaded  at  an 

absolute  memory  location 

Set  to  1  if  the  resource  requires  a  converter  routine 

when  being  loaded  into  memory  or  being  written  to 

disk 

Flags  passed  to  the  NewHandie  Memory  Manager 
tool  call  when  allocating  memory  for  the  resource 

File  ID  of  the  system  resource  file 
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■   Table  45-2      Resource  Manager  data  structures 


Name  OffsetA'alue    Type  Description 


ResHeaderRec  (resource  file  header  record) 


rFileVersion 

$0000 

LongWord 

Format  version  of  resource  fork 

rFileToMap 

$0004 

LongWord 

Offset  from  start  of  fork  to  resource 

map  record 

rFileMapSize 

$0008 

LongWord 

Size,  in  bytes,  of  resource  map 

rFileMemo 

$000C 

128  bytes 

Space  reserved  for  application  use 

rFileRecSize 

$008C 

Size  of  ResHeaderRec 

MapRec  (resource  map  record) 

mapNext 

$0000 

ndiiUic 

Handle  of  next  resource  map  in 

memory 

mapFlag 

$0004 

Word 

Bit  flags 

mapOf f set 

$0006 

LongWord 

Offset  from  start  of  fork  to  resource 

map  record 

mapSize 

$000A 

LongWord 

Size,  in  bytes,  of  resource  map 

mapToIndex 

$000E 

Word 

Offset  from  start  of  map  to 

mapFileNum 

$0010 

Word 

GS/OS  file  reference  number  for  open 

resource  file 

mapID 

$0012 

Word 

Resource  Manager  file  ID  assigned  to 

this  resource  file 

mapIndexSize 

$0014 

LongWord 

Total  number  of  resource  reference 

records  in  maplndex 

mapIndexUsed 

$0018 

LongWord 

Number  of  used  resource  reference 

records 

mapFreeListSize 

$001C 

Word 

Total  number  of  free  block  records  in 

mapFreeList 

mapFreeListUsed 

$001 E 

Word 

Number  of  used  free  block  records 

mapFreeList 

$0020 

n  bytes 

Array  of  free  block  records 

(FreeBlockRec) 

maplndex 

$0020+n 

m  bytes 

Array  of  resource  reference  records 

(ResRef Rec) 
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FreeBiockRec  (free  block  record) 

blkOffset 

$0000 

LongWord 

Offset,  in  bytes,  to  start  of  this  block 

of  free  space 

blkSize 

$0004 

LongWord 

Size,  in  bytes,  of  this  block  of  free 

space 

blkRecSize 

$0008 

Size  of  FreeBiockRec 

ResRef  Rec  (resource  reference  record) 

resType 

$0000 

Word 

Resource  type 

resID 

$0002 

LongWord 

Resource  ID 

resOf f set 

$0006 

LongWord 

Offset,  in  bytes,  from  start  of  resource 

fork  to  this  resource 

resAttr 

$000A 

Word 

Attribute  bit  flags  for  the  resource 

resSize 

$000C 

LongWord 

Size,  in  bytes,  of  the  resource  in  the 

resource  fork 

resHandle 

$0010 

Handle 

Handle  of  resource  in  memory 

resRecSize 

$0014 

Size  of  ResRef  Rec 
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m   Table  45-3      Resource  Manager  error  codes 


Code  Name  Description 


$1E01  resForkused  Resource  fork  not  empty 

$1E02  resBadFormat  Resource  fork  not  correctly  foraiatted 

$1E03  resNoConverter  No  converter  routine  available  for 

resource  type 

$1E04  resNoCurFiie  There  are  no  open  resource  files 

$1E05  resDupiD  Specified  resource  ID  is  already  in  use 

$1E06  resNotFound  Resource  was  not  found 

$1E07  resFiieNotFound  Resource  file  was  not  found 

$1E08  resBadAppiD  User  ID  not  found;  calling  program  has 

not  issued  ResourceStartUp  tOOl 

all 

$1E09  resNoUniqueiD  No  more  resource  IDs  available 

$1E0A  resindexRange  Index  is  out  of  range 

$1E0B  ressysisopen  System  file  is  already  open 

$1E0C  resHasChanged  Resource  marked  changed;  specified 

operation  not  allowed 
$1E0D  resDiff  Converter  Different  converter  already  logged  in 

for  this  resource  type 
|$1E0E  resDiskFuii  Volume  full 
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Chapter  46  Scheduler 


There  are  no  changes  in  the  Scheduler.  The  complete  reference  for  the 
Scheduler  is  in  Volume  2,  Chapter  19  of  the  Apple  IlGS  Toolbox  Reference. 
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Chapter  47  Sound  Tool  Set  Update 


This  chapter  documents  new  features  of  the  Sound  Tool  Set.  The 
complete  reference  to  the  Sound  Tool  Set  is  in  Volume  2,  Chapter  21  of 
the  Apple  IlGS  Toolbox  Reference. 

♦  Note:  You  must  read  the  Apple  IlGS  Hardware  Reference  to  understand 
some  of  the  concepts  presented  in  this  chapter. 
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Error  corrections 

This  section  provides  corrections  to  the  documentation  of  the  Sound  Tool  Set  in  the 
Apple  IIGS  Toolbox  Reference. 

m  The  documentation  of  the  FFSoundDoneStatus  call  includes  an  error.  You  will  note 
that  the  paragraph  that  describes  the  call  does  not  agree  with  the  "Stack  after  call" 
diagram.  The  text  states  that  the  call  returns  TRUE  if  the  specified  sound  is  still 
playing,  whereas  the  diagram  states  that  it  returns  FALSE  if  still  playing.  The  diagram, 
not  the  text,  is  correct. 

■  There  is  an  undocumented  distinction  between  a  generator  that  is  playing  a  sound  and 
one  that  is  active.  A  generator  that  is  playing  a  sound  returns  FALSE  in  response  to  an 
FFSoundDoneStatus  call.  One  that  is  active  may  or  may  not  be  playing  a  sound;  the 
value  of  the  flag  returned  by  FFSoundstatus  is  TRUE.  Active  generators  are  those 
that  are  allocated  to  a  voice.  At  any  given  moment  the  generator  may  be  playing  a 
sound,  and  so  the  FFSoundDoneStatus  returns  FALSE— or  it  may  be  silent  between 
notes,  in  which  case  FFSoundDoneStatus  returns  TRUE. 
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Clarification 

This  section  presents  more  complete  information  about  the  FFStartsound  tool  call, 
including  further  explanation  of  its  parameters,  a  new  error  code,  an  example  procedure 
for  moving  a  sound  from  the  Macintosh  to  the  Apple  IIGS  and  some  sample  code 
demonstrating  the  use  of  the  call.  The  original  documentation  for  this  call  is  in 
Chapter  20,  "Sound  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference. 


FFStartsound 

The  freeform  synthsizer  is  designed  to  play  back  long  wave  forms.  In  order  to  handle 
longer  waveforms  the  synthesizer  uses  two  buffers  (which  must  be  the  same  size), 
alternating  its  input  from  one  to  the  other.  When  the  synthesizer  exhausts  a  buffer,  it 
generates  an  interrupt  and  then  starts  reading  data  from  the  other  buffer.  The  Sound  Tool 
Set  services  the  interrupt  and  begins  refilling  the  empty  buffer.  This  process  continues 
until  the  waveform  has  been  completely  played. 

Note  that  all  synthesizer  input  buffers  must  be  buffer-size  aligned.  That  is,  if  you  have 
allocated  4K  buffers,  then  those  buffers  must  be  aligned  on  4K  memory  boundaries. 

Parameter  Block 


$00 

waveStart 

Long 

$04 

waveSlze 

Word 

$06 

freqOf fset 

Word 

$08 

docBuf fer 

Word 

$0A 

buf f erSize 

Word 

$0C 

nextWavePtr 

Long 

$10 

volSetting 

Word 
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waveStart 


waveSize 


f reqOf f set 


docBuf f er 


buf f erSize 


nextWavePtr 


volSetting 


The  starting  address  of  the  wave  to  be  played,  not  in  DOC  RAM  but  in 
Apple  IIGS  system  RAM.  The  Sound  Tool  Set  loads  the  waveform  data 
into  DOC  RAM  as  it  is  played. 

The  size  in  pages  of  the  wave  to  be  played.  A  value  of  1  indicates  that 
the  wave  is  one  page  (256  bytes)  in  size;  a  value  of  2  indicates  that  it 
is  two  pages  (512  bytes)  in  size— and  so  on  as  you  might  expect.  The 
only  anomaly  is  that  a  value  of  0  specifies  that  the  wave  is  65,536 
pages  in  size. 

This  parameter  is  copied  direcdy  into  the  Frequency  High  and 
Frequency  Low  registers  of  the  DOC.  See  the  previous  discussion  of 
those  registers  for  more  complete  information. 

Contains  the  address  in  Sound  RAM  where  buffers  are  to  be  allocated. 
This  value  is  written  to  the  DOC  WaveForm  Jable  Pointer  register.  The 
low-order  byte  is  not  used,  and  should  always  be  set  to  0. 

The  lowest  three  bits  set  the  values  for  the  table-size  and  resolution 
portions  of  the  DOC  Bank-Select/Table-size/Resolution  register.  See 
the  previous  discussion  of  that  register  for  details. 

This  is  die  address  of  the  next  waveform  to  be  played.  If  the  field's 
value  is  0,  then  the  current  waveform  is  the  last  waveform  to  be 
played. 

The  low  byte  of  the  voisetting  field  is  copied  directly  into  the 
Volume  register  of  the  DOC.  All  possible  byte  values  are  valid. 


New  error  code 


$0817      iRQNotAssignedErr     No  master  IRQ  was  assigned. 
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Moving  a  sound  from  the  Macintosh  to  the  Apple  IIGS 

To  move  a  digitized  sound  from  the  Macintosh  to  the  Apple  IlGS  and  play  the  sound,  you 
will  have  to  perform  the  following  steps 

1 .  Save  the  sound  as  a  pure  data  file  on  the  Macintosh. 

2.  Transfer  the  file  to  the  Apple  IlGS  (using  Apple  File  Exchange,  for  example). 

3.  Filter  all  the  zero  sample  bytes  out  of  the  file  by  replacing  them  with  bytes  set  to  $01. 
This  is  very  important,  because  the  Apple  IlGS  interprets  zero  bytes  as  the  end  of  a 
sample. 

4.  Load  the  sound  into  memory  with  GS/OS  calls. 

5.  Play  the  sound  with  the  FFStartsound  tool  call. 

Set  the  f  reqof  f  set  parameter  to  $01B7  in  order  to  play  the  sound  at  the  same 
tempo  as  the  Macintosh. 


Sample  code 

This  assembly-language  code  sample  demonstrates  the  use  of  the  FFStartsound  tool 
call. 

PushWord        chanGenType         ;   set  generator  for  FFSynth 
PushLong        #STParamBlk        ;  address  of  parm  block 
FFStartsound  ;   start  free-from  synth 


ChanGenType 

DC 

.W 

$0201 

STParamBlk 

DS 

.L 

1 

Entry 

WaveSize 

DS 

.W 

1 

Freq 

DC 

.w 

$200 

Start 

DC 

.w 

$8000 

Size 

DC 

.w 

$6 

Nxtwave 

DC 

.L 

$0 

Vol 

DC 

.W 

$FF 

WaveSize 


generator  2,  FFSynth 

store  the  address  of  the 
sound  in  system  memory  here 

store  the  number  of  pages  to 

play  here 
A9  set  for  each  sample  once 
start  at  beginning 
16k  buffers 
no  new  param  block 
maximum  volume 
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New  information 

This  section  provides  new  inforniation  about  the  Sound  Tool  Set. 

■  The  four  sound  and  music  tools,  that  is,  die  Note  Sequencer,  Note  Syntiiesizer,  MIDI 
Tool  Set,  and  Sound  Tool  Set,  work  together  and  must  have  compatible  versions.  The 
current  required  versions  are: 

Sound  Tool  Set  version  2.4 

Note  Synthesizer  version  1.3 

Note  Sequencer  version  1.3 

MIDI  Tool  Set  version  1.2 

■  The  Sound  Tool  Set  soundBootmit  call  has  been  changed  to  initialize  tiie 
MidiinitPoii  vector  ($E101B2)  to  an  rtl. 

■  The  setuserSoundiRQv  tool  call  allows  you  to  establish  a  custom  syntiiesizer 
interrupt  handler.  In  addition  to  tiie  description  in  tiie  Toolbox  Reference,  note  tiiat 
your  internipt  handler  should  verify  tiiat  it  should  handle  the  interrupt  by  checking  tiie 
syntiiesizer  mode  value,  which  is  passed  as  an  input  parameter  to  die  interrupt  handler 
in  the  accumulator  register. 

If  your  routine  does  not  process  die  interrupt,  it  should  ihake  a  jmp  to  die  next  routine 
in  die  interrupt  chain,  taking  care  to  preserve  die  state  of  die  accurnulator.  If  your 
routine  does  process  tiie  interaipt,  it  should  set  die  carry  flag  to  0  and  return  via  an  rtl 
instruction. 
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Introduction  to  sound  on  the  Apple  IIGS 

This  section  provides  some  general  background  on  the  various  sound-related  tool  sets 
available  on  the  Apple  IIGS.  There  are  five  sound  tool  sets:  the  Sound  Tool  Set,  the  Note 
Sequencer,  the  Note  Synthesizer,  the  MIDI  Tool  Set,  and  the  Audio  Compression  and 
Expansion  (ACE)  Tool  set.  Although  each  provides  distinct  functionality,  they  can 
complement  one  another  and  generate  fairly  sophisticated  sound  applications. 

■  The  Sound  Tool  Set  will  play  back  a  digitized  sample  of  any  length  and  at  any 
frequency.  Note  that  the  sample  must  fit  into  system  memory. 

■  The  Note  Synthesizer  also  plays  digitized  samples,  but  with  much  greater  control  over 
the  sample,  including  the  ability  to  loop  within  the  sample  and  control  the  sound 
envelope,  but  is  limited  to  sounds  smaller  than  65,536  bytes. 

■  The  MIDI  Tool  Set  allows  you  to  send  and  receive  MIDI  data. 

■  The  Note  Sequencer  combines  the  functionality  of  die  Note  Synthesizer  and  MIDI 
Tool  Set,  allowing  you  to  send  MIDI  data  and  drive  the  Note  Synthesizer 
simultaneously. 

■  The  Audio  Compression  and  Expansion  Tool  Set  provides  dramatic  reduction  in 
sound  disk-storage  requirements,  with  only  slight  degradation 'in  sound  quality. 

By  combining  the  facilities  offered  by  these  tools,  you  can  easily  build  impressive  sound 
applications.  For  example,  you  could  develop  a  program  that  reads  MIDI  data  into  the 
Note  Synthesizer  while  also  saving  that  data  to  disk  for  later  input  to  the  Note  Sequencer. 
This  program  would  turn  the  Apple  IIGS  into  a  MIDI  sound  source  with  the  capaibility  to 
save  its  songs  for  later  playback. 
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Note  Sequencer 

The  DOC  interrupts  that  drive  the  Note  Synthesizer  also  drive  the  Note  Sequencer.  Before 
the  Note  Synthesizer  handles  an  interrupt,  it  passes  it  to  the  Note  Sequencer  and  allows 
other  interrupt  handlers  access  to  it  before  taking  control.  The  Note  Sequencer  checks  its 
increment  value  against  its  clock  value  to  determine  whether  to  take  any  action.  If  enough 
time  has  passed,  it  checks  for  delay;  if  a  delay  is  specified,  it  checks  to  determine 
whether  it  has  waited  long  enough  to  satisfy  the  delay  requirement.  If  it  hasn't,  it  simply 
returns.  If  it  has  waited  long  enough,  then  it  checks  all  playing  notes  with  specified 
durations  to  determine  whether  it  is  time  to  turn  them  off.  If  so,  it  turns  those  notes  off. 
It  then  parses  the  next  seqitem  in  the  current  sequence  and  makes  Note  Synthesizer  and 
MIDI  Tool  Set  calls  to  execute  it.  If  the  chord  bit  is  set  in  the  current  seqitem,  it 
immediately  fetches  the  next  seqitem  for  execution.  If  the  delay  bit  is  set,  then  it 
calculates  the  required  delay  and  sets  the  delay  flag.  It  then  returns. 


Note  Synthesizer 

One  DOC  oscillator  drives  the  Note  Synthesizer  and  the  Note  Sequencer,  using  the 
interrupts  that  it  generates  at  the  end  of  waveforms,  or  at  0  values  in  the  waveform.  The 
Sound  Tool  Set  services  such  interrupts,  then  passes  them  to  the  Note  Synthesizer  for 
further  handling  if  it  is  needed.  Because  the  Sound  Tool  Set  and  the  Note  Synthesizer  use 
the  same  direct-page  space,  it  is  appropriate  to  use  the  Note  Synthesizer  to  assign 
oscillators  for  your  own  purposes  even  if  you  don't  use  the  Note  Synthesizer  any  further 
with  the  assigned  oscillators. 

The  Note  Synthesizer's  operation  requires  considerable  processing.  If  processor  time  is  in 
short  supply  and  you  want  to  use  the  Note  Synthesizer  to  produce  sounds,  use  envelopes 
that  are  simple  and  do  not  use  vibrato,  and  use  low  updateRate  values.  See 
Chapter  41,  "Note  Synthesizer,"  in  this  book  for  further  information. 

The  Note  Synthesizer  and  Note  Sequencer  run  at  interrupt  time,  and  current  versions  are 
fully  compatible  with  the  MIDI  Tool  Set. 
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Sound  General  Logic  Unit  (GLU) 

One  quirk  of  the  sound  general  logic  unit  (GLU)  is  that  the  value  for  volume  in  the  control 
register  is  a  write-only  value.  It  is  possible,  however,  to  maintain  the  system  volume 
specified  by  the  Control  Panel  setting  and  still  write  to  the  GLU.  To  find  the  system 
volume  setting,  use  the  Miscellaneous  Tool  Set's  GetAddr  call  to  find  the  address  of 
IRQ .  volume  and  use  the  value  stored  at  that  address. 


Vocabulary 

This  section  describes  a  number  of  terms  that  have  special  meanings  in  the  context  of  the 
Apple  IIGS  Digital  Oscillator  Chip  (DOC). 

Oscillator 

There  are  32  oscillators  on  the  DOC.  They  are  not  true  oscillators  in  the  ordinary  sense  of 
a  circuit  that  generates  a  waveform.  Rather,  they  are  circuits  that  take  as  input  a 
waveform  stored  as  digital  data,  and  output  an  audio  signal  based  on  those  data. 

Generator 

Each  generator  used  by  the  Sound  Tool  Set  is  actually  a  pair  of  DOC  oscillators,  usually 
operating  in  swap  mode  when  used  by  the  Sound  Tool  Set.  In  swap  mode  the  two 
oscillators  alternate  playing  and  halting,  with  each  oscillator  playing  while  the  other  is 
halted.  When  one  oscillator  reaches  the  end  of  its  current  waveform,  it  stops  playing  and 
the  other  oscillator  takes  over,  until  it  reaches  the  end  of  its  waveform  and  the  first 
oscillator  takes  over  again. 

Voice 

A  single  audio  signal  that  can  be  independently  controlled.  A  synthesizer  that  can  play 
eight  notes  at  one  time  is  normally  said  to  have  eight  voices. 
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Sample  rate 

A  waveform  is  stored  in  the  Apple  IIGS  computer's  memory  as  some  number  of  digital 
samples  of  a  sound.  The  number  of  samples  that  the  Apple  IIGS  plays  each  second  is 
referred  to  as  the  sample  rate.  The  sample  rate  of  the  DOC  is  fixed  by  the  number  of 
oscillators  that  are  enabled,  that  is,  by  the  value  of  register  $E1  on  the  DOC.  The  sample 
rate  depends  only  upon  this  value;  changing  other  parameters  does  not  affect  sample  rate. 


where 

S  is  the  sample  rate 

C  is  the  input  clock  rate,  which  is  always  7.159  MHz 

O  is  the  number  of  oscillators  enabled  (32  is  standard) 

The  default  sample  rate,  with  all  32  oscillators  enabled,  is  about  26.31985  kHz;  that  is  to 
say,  the  Apple  IIGS,  operating  at  its  default  sample  rate,  plays  about  26,320  samples  per 
second.  It  is  possible  to  generate  higher  sampling  rates  by  reducing  the  number  of  enabled 
oscillators.  However,  the  low-pass  filter  on  the  Apple  IIGS  is  a  5-pole  Chebyshev  active 
filter  with  a  roll-off  at  10  KHz.  Consequently,  higher  sampling  rates  may  not  result  in  higher 
perceived  sound  quality. 

Drop  sample  timing 

The  DOC  plays  waveforms  by  looking  up  wave  data  in  a  table  in  memory  and  sweeping 
through  a  stored  waveform.  This  strategy  has  the  advantage  that  it  can  produce  very 
faithful  reproductions  of  digitally  sampled  sound.  If,  however,  you  want  the  DOC  to  play 
a  waveform  at  a  pitch  different  from  that  at  which  it  was  recorded,  it  cannot  simply 
generate  it  at  a  different  frequency  as  a  true  voltage-controlled  oscillator  can.  Instead,  the 
DOC  changes  the  pitch  by  using  a  method  called  drop  sample  tmiing.  To  raise  the  pitch 
of  a  sample  one  octave,  the  DOC  doubles  its  frequency  by  skipping  every  other  sample  in 
the  sequence.  Similarly,  to  lower  the  pitch  one  octave,  it  cuts  the  frequency  in  half  by 
playing  each  sample  in  the  sequence  twice. 

The  disadvantage  of  drop  sample  tuning  is  that  at  higher  frequencies,  some  of  the  samples 
are  dropped,  or  lost,  and  changing  the  pitch  also  changes  the  duration  of  each  waveform. 
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Frequency 

Frequenq?  refers  both  to  the  output  frequency  of  the  audio  signal  generated  by  the  DOC 
and  to  the  value  of  the  DOC  frequency  register.  We  normally  mean  the  value  of  the 
rrequency  register,  which  determines  but  is  not  equal  to,  the  output  frequency.  Frequency 
direcdy  determines  the  perceived  pitch  of  a  sound;  higher  frequencies  are  higher  pitches. 

Sound  RAM 

The  DOC  has  64  KB  of  random-access  memory  dedicated  to  storage  of  sound  samples. 
This  RAM,  which  contains  the  sampled  waveforms  the  DOC  plays,  is  referred  to  as 
Sound  RAM. 

Waveform 

A  waveform  consists  of  data  representing  the  stored  form  of  a  digitally  sampled  audio 
signal. 

DOC  registers 

There  are  ten  different  registers  in  the  DOC.  There  is  a  set  of  registers  for  each  of  the  DOC 
oscillators.  That  is,  each  of  the  first  seven  registers  has  32  different  values,  one  for  each 
DOC  oscillator.  The  registers  are  Frequency  Low,  Frequency  High,  Volume,  Waveform 
Data  Sample,  Waveform  Table  Pointer,  Control,  Bank  Select/Table-Size/Resolution, 
Oscillator  Interrupt,  Oscillator  Enable,  and  A/D  Converter. 
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Frequency  registers 

Two  8-bit  frequency  registers,  Frequency  Low  and  Frequency  High,  are  paired  to  produce 
a  single  l6-bit  frequency  value.  The  output  frequency  of  a  sample  an  be  represented  by 


where 

O        is  the  output  frequency  in  hertz,  assuming  that  one  cycle  of  the  sound 

exactly  fills  the  table  size 
S        is  the  sample  rate  (26.32  KHz) 

R        is  the  resolution  value  in  the  Bank-Select/Table-Size/Resolution  register; 

valid  values  lie  in  the  range  from  0  through  7 
FHL     is  the  combined  values  of  Frequency  Low  and  Frequency  High;  valid 

values  lie  in  the  range  from  0  through  65,535 

This  calculation  assumes  that  the  wave  table  contains  exactly  one  cycle  of  the  waveform. 
The  resolution  and  the  table  size  are  3-bit  values,  and  this  calculation  assumes  they  are 
equal. 

If  one  cycle  of  the  sound  does  not  exactly  fill  the  table  size,  then  you  can  use  the  following 
formula  to  calculate  the  output  frequency: 


/_Fi_\    /  S*FHL  \ 

VSRiy  *  V2^«-™v 


where 

O        is  the  output  frequency  in  hertz 

Fi       is  the  frequency  of  the  sampled  waveform  in  hertz 

SRi      rate  at  which  you  sampled  the  original  sound  (in  samples  per  second) 

S        is  the  Apple  IIGS  sample  rate  (26.32  KHz) 

FHL     is  the  combined  values  of  Frequency  Low  and  Frequency  High;  valid 

values  lie  in  the  range  from  0  through  65,535 
R        is  the  resolution  value  in  the  Bank-SelectA'able-Size/Resolution  register; 

valid  values  lie  in  the  range  from  0  through  7 
TAB     Table-size  value  in  the  Bank-select/Table-size/Resolution  register;  valid 

values  lie  in  the  range  from  0  through  7 
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Volume  register 

The  value  in  the  Volume  register  directly  controls  the  volume  of  the  sound  output  for  that 
oscillator. 

Waveform  Data  Sample  register 

This  is  a  read-only  register  that  always  contains  the  value  of  the  sample  that  an  oscillator  is 
currently  playing. 

Waveform  Table  Pointer  register 

This  register  is  also  referred  to  as  the  Address  Pointer  register.  It  identifies  which  page  of 
Sound  RAM  contains  the  start  of  the  current  sample.  The  ff  start  sound  parameter 
docBuffer  is  written  directly  to  this  register. 

Control  register 

The  Control  register  establishes  several  attributes  of  its  associated  oscillator.  These 
attributes  include  the  oscillator's  mode,  whether  the  oscillator  is  halted,  whether  it  will 
generate  an  interrupt  at  the  end  of  its  cycle,  and  the  channel  to  which  the  oscillator  is 
assigned. 

■  Interrupt  enable  bit  Bit  3  of  the  Control  register  is  the  internipt  enable  bit.  When  this 
bit  is  set  to  1,  the  oscillator  generates  an  interrupt  when  it  reaches  the  end  of  a 
waveform  or  plays  a  sample  with  a  value  of  0. 

Unless  you  have  issued  the  setsouncJMiRQv  tool  call  to  set  a  custom  interrupt  vector 
(see  Chapter  20,  "Sound  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference  for  more 
information),  the  Sound  Tool  Set  fields  these  interrupts  first.  Upon  entry  to  the 
internipt  routine,  the  accumulator  register  contains  the  low-order  nibble  of  the 
genNumFFSynth  parameter  from  the  FFStartSound  tool  call  that  assigned  the 
oscillator.  If  the  value  of  this  nibble  indicates  that  the  interrupt  is  for  the  Sound  Tool 
Set,  the  intemjpt  handler  processes  the  interrupt.  Otherwise,  it  passes  the  interrupt  on 
to  other  interrupt  routines  (see  the  discussion  of  the  setuserSoundiRQv  tool  call  in 
Chapter  20,  "Sound  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference  for  information  on 
setting  vectors  to  user  interrupt  routines). 
•  Mode  The  mode  value  consists  of  two  bits,  MO  and  Ml.  There  are  thus  four  possible 
modes,  which  are  designated  as  free-run  mode  or  loop  mode  (00),  one-shot  mode  (01), 
sync/AM  mode  (10),  and  swap  mode  (11). 
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In  free-ain  or  loop  mode,  the  oscillator  sweeps  through  a  waveform  to  the  end,  playing 
the  values  it  encounters,  then  starts  again  at  the  beginning  of  the  waveform  and 
generates  an  interrupt  if  the  interrupt  enable  bit  is  set  to  1.  The  generator  also 
interrupts  if  it  encounters  a  0,  or  if  it  reaches  the  end  of  the  waveform. 

In  one-shot  mode,  the  oscillator  sweeps  through  its  waveform  to  the  first  0  value  or  to 
the  end,  generates  an  interrupt  if  the  interrupt  enable  bit  is  setto  1,  and  halts. 

In  swap  mode,  an  oscillator  sweeps  through  its  waveform  to  the  first  0  value,  or  to  the 
end  of  the  waveform,  generates  an  interrupt,  and  halts,  turning  control  over  to  a 
partner  oscillator.  Only  one  halt  bit  an  be  set  to  1  at  any  given  time  for  a  pair  of 
oscillators  in  swap  mode;  setting  the  halt  bit  of  one  oscillator  to  1  forces  the  other's  to 
0. 

Generators  always  consist  of  an  even/odd  pair  of  oscillators— for  example,  oscillators 
0  and  1  form  a  generator,  as  do  oscillators  2  and  3,  and  so  on.  The  Note  Synthesizer 
normally  uses  each  pair  with  the  even-numbered  oscillator  in  swap  mode  and  the  odd- 
numbered  oscillator  in  loop  mode.  The  Sound  Tool  Set  normally  uses  both  oscillators 
of  a  pair  in  swap  mode. 

Channel  register 

The  Channel  register  specifies  a  sound's  stereo  position.  Currently,  only  the  low-order  bit  is 
significant.  A  value  of  0  in  this  bit  sets  the  oscillator's  stereo  position  to  the  right  channel; 
a  value  of  1  sets  it  to  the  left  channel. 

Bank-Select/Table-Size/Resolution  register 

This  register  sets  the  table  size  for  stored  waveforms,  the  resolution  of  the  waveform,  and 
the  bank  selection  for  the  oscillator.  When  it  plays  a  sound,  the  DOC  adds  the  value  of  the 
Frequency  register  to  its  accumulator.  It  multiplexes  the  resulting  value  with  the  address 
pointer  to  determine  the  address  in  DOC  RAM  of  the  sample  to  play.  The  table  size 
determines  how  many  bits  of  the  Address  Pointer  register  are  accessible  to  the  DOC  for 
this  operation;  a  larger  table  size  reduces  the  number  of  Address  Pointer  register  bits  used 
in  the  address  calculation,  and  reduces  the  precision  with  which  a  particular  sample  can  be 
located.  If  eight  bits  of  the  Address  Pointer  register  are  used  to  locate  the  next  sample, 
the  DOC  can  distinguish  twice  as  many  starting  points  as  it  can  if  only  seven  bits  are  used. 

Each  time  the  DOC  cycles  it  adds  the  contents  of  the  Frequency  register  to  its  24-bit 
accumulator.  It  then  appends  a  subrange  of  the  accumulator's  24  bits  to  the  value  of  the 
address  pointer  and  uses  the  resulting  value  as  an  absolute  address  in  DOC  RAM.  It  then 
plays  the  sample  stored  at  that  location. 

The  resolution  value,  which  is  the  lowest  dvee  bits  of  the 

Bank-Select/Table-Size/Resolution  register,  determines  the  lowest  bit  of  the  accumulator 
value  that  will  be  appended  to  the  address  pointer. 
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The  table-size  value,  which  is  the  next  three  bits  above  the  resolution,  determines  both 
width  of  the  address  pointer  value  and  the  width  of  the  accumulator  value.  The  width  of 
each  value  is  the  number  of  bits  the  DOC  uses  from  that  register.  For  example,  the  DOC 
accumulator  is  a  24-bit  register,  but  the  DOC  uses  only  eight  of  those  bits  when  the  table 
size  is  256  bytes. 

The  DOC  uses  only  part  of  each  register,  the  accumulator  and  the  address  pointer,  to 
determine  the  place  in  memory  that  it  will  play  next.  For  any  table  size  greater  than  256 
bytes  (1  page),  it  overwrites  the  lowest  bits  of  the  address  pointer  with  bits  from  the 
accumulator.  Figure  47-1  shows  the  correspondence  between  table  size,  resolution,  and 
the  portions  of  the  Address  Pointer  register  and  accumulator  used  to  determine  the 
location  of  the  next  sample  to  be  played. 


■   Figure  47-1     DOC  registers 
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The  resolution  acts  as  an  offset  value,  determining  which  bit  is  the  lowest  accumulator  bit 
to  be  appended  to  the  Address  Pointer  register.  The  effect  of  these  computations  is  that 
if  you  increase  the  resolution  by  1,  the  pitch  of  the  waveform  will  be  one  octave  lower.  If 
you  increase  the  resolution  value  by  2,  the  pitch  will  be  four  octaves  lower— and  so  on  in 
powers  of  two, 

The  table-size  value  is  a  3-bit  value  that  is  equal  to  the  resolution  value  in  calls  to 
FFStartSound.  It  Specifies  the  size  of  the  DOC  RAM  partitions  used  to  contain 
waveforms  that  are  to  be  played.  The  correspondence  between  table-size  values  and  the 
table  sizes  is 


Table-size 

3-bit  value 

RAM  buffer  size 

0 

000 

1  page  (256  bytes) 

1 

001 

2  page  612  bytes) 

2 

010 

4  pages  (1024  bytes) 

3 

oil 

8  pages  (2048  bytes) 

4 

100 

16  pages  (4096  bytes) 

5 

101 

32  pages  (8192  bytes) 

6 

110 

64  pages  (16,384  bytes) 

7 

111 

128  pages  (32,768  bytes) 

Both  the  table-size  and  resolution  values  are  copied  into  their  respective  bits  in  the 
Bank-Select/Table-Size/Resolution  register  from  the  lowest  three  bits  of  the  buffersize 
parameter  to  the  FFStartsound  call. 

•  Bank-select  bit  The  bank-select  bit  is  bit  6.  It  is  reserved  for  the  use  of  Apple 
Computer,  Inc.  and  should  always  be  0. 

Oscillator  Interrupt  register 

This  register  contains  a  bit  that  specifies  whether  an  interrupt  has  occurred  and,  if  so, 
contains  the  number  of  the  oscillator  that  generated  the  interrupt.  The  oscillator  number 
(0-31)  is  stored  in  bits  1  through  5  of  this  register. 

Oscillator  Enable  register 

The  Oscillator  Enable  register  specifies  the  number  of  enabled  oscillators  (0-31). 
A/D  Converter  register 

This  register  always  contains  the  current  sample  from  the  analog-to-digital  converter  built 
into  the  Digital  Oscillator  Chip. 
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MIDI  and  interrupts 

The  MIDI  Tool  Set  automatically  recovers  incoming  MIDI  data,  but  to  do  so  it  requires 
that  interrupts  never  be  disabled  for  longer  than  290  microseconds.  If  an  application 
disables  interrupts  for  longer  than  this,  it  should  call  the  MidiinputPoii  vector  at  least 
every  270  microseconds  to  ensure  that  the  data  are  properly  received  and  the  input  buffer 
is  cleared.  When  MIDI  input  is  not  enabled,  the  vector  is  still  serviced,  but  at  minimal  cost 
in  CPU  cycles.  Under  these  circumstances,  the  call  to  the  vector  sacrifices  only  two 
instructions,  namely  a  jsl  and  an  rtl. 

Normally  one  CPU  cycle  on  the  Apple  IlGS  lasts  about  1  microsecond,  but  it  may  take 
slighdy  longer  if  it  accesses  soft  switches  or  slow  memory. 
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New  Sound  Tool  Set  calls 

There  are  four  new  tool  calls  that  provide  greater  flexibility  when  playing  free-form 
sounds.  The  FFSetupSound  and  FFStartPiaying  alls  allow  you  to  schedule  a  sound 
for  playback  at  a  later  time.  setDOCReg  and  ReadDOCReg  provide  easy  access  to  the 
DOC  registers. 


FFSetupSound  $1508 

This  call  is  identical  to  the  FFStartSound  tool  call,  but  does  not  actually  start  playing 
the  specified  sound.  Use  the  FFStartPiaying  tool  call  to  start  playing.  This  call  gives 
you  tiie  option  of  setting  up  a  sound  and  playing  it  later. 

Parameters 

Stack  before  call 


Previous  contents 


channelGen 


-  paramBlockPtr  - 


Stack  after  call 


Word— Channel,  generator  type  word 

Long— Pointer  to  FFStartsound  parameter  block 

<— SP 


Previous  contents 


Errors 
C 


channelGen 


None 


<— SP 


extern  pascal  void  FFSetupSound (channelGen, 
paramBlockPtr) ; 


Word 
Pointer 


channelGen; 
paramBlockPtr; 


For  complete  information  on  the  channelGen  parameter,  refer  to  the 

description  of  the  FFStartSound  tool  call  in 

Chapter  20,  "Sound  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference 
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paramBlockPtr     For  complete  information  on  the  parameter  bloclc  pointed  to  by  the 
paramBlockPtr  pzTzmeter,  see  "FFStartsound"  earlier  in  this 
chapter. 
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FFStartPlaying  $l608 

Starts  playing  the  sound  specified  by  tlie  FFSetupSound  tool  call  on  a  specified  set  of 
generators.  Your  program  passes  a  parameter  to  this  call  indicating  which  generators  are  to 
play  the  sound. 

Parameters 

Stack  before  call 


Previous  contents 


genWord 


Stack  after  call 


Word— Flag  word  indicating  which  generators  to  start 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  FFStartPlaying (genWord) ; 


genWord 


Word 


genWord; 


Specifies  which  generators  to  start.  Each  bit  in  the  word  corresponds 
to  a  generator.  Setting  a  bit  to  1  indicates  that  the  matching  generator 
is  to  play  the  sound.  For  example,  a  genWord  vzht  of  $4071 
(%0100  0000  0111  0001)  would  start  generators  0,  4,  5,  6,  and  14. 


▲  Warning     A  value  of  $0000  for  this  parameter  is  illegal  and  will 
cause  the  system  to  hang.  ▲ 
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ReadDOCReg  $1808 

Reads  the  DOC  registers  for  a  generator's  oscillator  and  stores  the  register  contents  in  a 
special  format  in  the  target  memory  location.  Your  program  specifies  the  generator  and 
which  oscillator,  as  well  as  the  destination  for  the  register  information.  The  format  of  the 
resultant  data  structure  corresponds  to  the  input  to  the  SetDOCReg  tool  call. 


▲  Warning     This  is  a  very  low-level  call.  You  should  not  use  it  unless 
you  have  a  thorough  understanding  of  the  DOC.  This 
call  may  not  be  supported  in  future  versions  of  the 
system  hardware.  ▲ 


Parameters 

Stack  before  call 


Previous  contents 


-dRegParmBlkPtr  - 


Long— Pointer  to  DOC  register  parameter  block 
<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 


<— SP 
None 

extern  pascal  void  ReadDOCReg (dRegParmBlkPtr) ; 
Pointer  dRegParmBlkPtr; 
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dRegPamBlkPtr  Refers  to  a  location  in  memory  to  be  loaded  with  the  contents  of  the 
DOC  registers  for  the  specified  generator. 


$00 

—        oscGenType  — 

Word— (see  below) 

$02 

freqLowl 

Byte— Frequenqf  Low  register  for  first  oscillator 

$03 

freqHighl 

Byte— Frequency  High  register  for  first  oscillator 

$04 

voll 

Byte— Volume  register  for  first  oscillator 

$05 

tablePtrl 

Byte— Waveform  Table  Pointer  register  for  first  oscillator 

$06 

cont roll 

Byte— Control  register  for  first  oscillator 

$07 

tableSizel 

Byte— Table-size  register  for  first  oscillator 

$08 

freqLow2 

Byte— Frequency  Low  register  for  second  oscillator 

$09 

freqHighZ 

Byte— Frequency  High  register  for  second  oscillator 

$0A 

vol2 

Byte— Volume  register  for  second  oscillator 

$0B 

tablePtr2 

Byte— Waveform  Table  Pointer  register  for  second  oscillator 

$0C 

control2 

Byte— Control  register  for  second  oscillator 

$0D 

tableSize2 

Byte— Table-size  register  for  second  oscillator 

oscGenType         Bits  8  through  11  specify  the  generator  number  ($0  through  $F) 
whose  registers  are  to  be  retrieved. 

bit  15         Determines  whether  to  get  DOC  registers  for  the  first 
oscillator. 
1  -  Get  the  registers 

0  -  Do  not  get  the  registers 
bit  14         Determines  whether  to  get  DOC  registers  for  the  second 

oscillator. 

1  -  Get  the  registers 
0  -  Do  not  get  the  registers 

bits  12-13     Reserved;  must  be  set  to  0. 
bits  8-11      Specify  the  generator  number  for  the  operation.  Valid 

values  lie  in  the  range  from  $0  through  $F. 
bits  4-7       Reserved;  must  be  set  to  0. 
bits  0-3       Specify  who  is  using  the  generator  (this  value  is 
returned) 
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SetDOCReg  $1708 


Sets  the  DOC  registers  for  a  generator's  oscillator  from  register  contents  stored  in  a  special 
format.  Your  program  specifies  the  generator,  the  oscillator(s)  and  the  register 
information.  The  format  of  the  input  data  structure  corresponds  to  the  output  from  the 
ReadDOCReg  tOOl  call. 


▲  Warning     This  is  a  very  low-level  all.  You  should  not  use  it  unless 
you  have  a  thorough  understanding  of  the  DOC.  This 
call  may  not  be  supported  in  future  versions  of  the 
system  hardware.  ▲ 


Parameters 

Stack  before  call 


Previous  contents 


-dRegParmBlkPtr  ■ 


Stack  after  call 


Long— Pointer  to  DOC  register  parameter  block 
<— SP 


Previous  contents 


Errors 
C 


None 


<— SP 


extern  pascal  void  SetDOCReg (dRegParmBlkPtr) ; 
Pointer  dRegParmBlkPtr; 
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dRegParmBlkPtr  Refers  to  a  location  in  memory  containing  the  new  contents  of  the 
DOC  registers  for  the  specified  generator: 


$00 

—  oscGenType 

$02 

f reqLowl 

$03 

freqHlghl 

$04 

voll 

$05 

tablePtrl 

$06 

control 1 

$07 

tableSizel 

$08 

f reqLow2 

$09 

freqHigh2 

$0A 

vol2 

$0B 

tablePtr2 

$0C 

control2 

$0D 

tableSize2 

Word— <see  below) 

Byte— Frequenq'  Low  register  for  first  oscillator 

Byte— Frequenqf  High  register  for  first  oscillator 

Byte— Volume  register  for  first  oscillator 

Byte— Waveform  Table  Pointer  register  for  first  oscillator 

Byte— Control  register  for  first  oscillator 

Byte— Table-size  register  for  first  oscillator 

Byte— Frequency  Low  register  for  second  oscillator 

Byte— Frequency  High  register  for  second  oscillator 

Byte— Volume  register  for  second  oscillator 

Byte— Waveform  Table  Pointer  register  for  second  oscillator 

Byte— Control  register  for  second  oscillator 

Byte— Table-size  register  for  second  oscillator 


oscGenT^e         Specifies  the  generator  whose  oscillators  are  to  be  written,  along  with 
other  generator  control  block  (GCB)  information  (see 
Chapter  41,  "Note  Synthesizer,"  in  this  book  for  detailed  information 
on  the  format  and  content  of  the  GCB): 

bit  15         Determines  whether  to  set  DOC  registers  for  the  first 
oscillator. 
1  -  Set  the  registers 

0  -  Do  not  set  the  registers 

bit  14         Determines  whether  to  set  DOC  registers  for  the  second 
oscillator. 

1  -  Set  the  registers 

0  -  Do  not  set  the  registers 
bits  12-13    Reserved;  must  be  set  to  0. 
bits  8-11      Specify  the  generator  number  for  the  operation.  Valid 

values  lie  in  the  range  from  $0  through  $F. 
bits  4-7       Reserved;  must  be  set  to  0. 
bits  0-3       Specify  who  is  using  the  generator. 

$0  -  Invalid  value 

$1  -  Free-form  synthesizer 

$2  -  Note  Synthesizer 

$3  -  Reserved 

$4  -  MIDI 

$5-$7  -  Reserved 

$8-$F  -  User-defined 
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Chapter  48  Standard  File  Operations  Tool  Set 


This  chapter  documents  new  features  of  the  Standard  File  Operations 
Tool  Set.  The  complete  reference  to  this  tool  set  is  in  Volume  2, 
Chapter  22  of  the  Apple  IlGS  Toolbox  Reference. 
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New  features  in  the  Standard  File  Operations  Tool  Set 

This  section  explains  new  features  of  the  Standard  File  OperationsTool  Set. 

■  The  Standard  File  Operations  Tool  Set  now  uses  Class  1  calls  to  fully  support  GS/OS.  As 
a  result,  new  tool  set  calls  accept  full  GS/OS  filenames  and  pathnames: 

□  A  total  of  13,107  files,  with  a  total  of  up  to  64  KB  of  name  strings,  can  reside  in  a 
single  folder. 

□  A  filename  can  now  contain  up  to  253  characters. 

□  A  pathname  can  now  contain  up  to  508  characters. 

New  applications  should  use  the  new  tool  set  calls  to  gain  access  to  this  functionality. 

♦  Note:  Since  old  The  Standard  File  Operations  Tool  Set  calls  use  the  new,  longer 
filenames  and  pathnames  internally,  it  is  possible  for  an  old-style  Get  or  Put  call  to 
access  an  AppleShare®  file  with  a  name  that  is  more  than  15  characters  long.  In  this 
case,  the  system  truncates  the  filename  in  the  reply  record.  If  necessary,  the  pathname 
is  also  truncated.  Note,  however,  that  if  the  pathname  will  fit  in  the  reply  record,  then 
it  is  returned  intact,  regardless  of  the  length  of  the  filename  portion  of  the  path.  As  a 
result,  this  representation  of  the  filename  may  exceed  15  characters.  While  this  allows 
the  application  to  open  the  file,  programs  that  cannot  accept  a  filename  with  more 
than  15  characters  may  not  function  predictably. 

■  The  Standard  File  Operations  Tool  Set  now  uses  the  List  Manager  for  some  internal 
functions,  freeing  up  memory  for  application  use. 

■  The  Standard  File  Operations  Tool  Set  now  requires  that  there  be  four  pages  available 
on  the  application  stack  (three  for  List  Manager,  one  for  the  Standard  File  Operations 
Tool  Set  itselO. 

■  The  new  tool  calls  use  prefixes  differendy.  These  calls  first  check  prefix  8  for  a  valid 
path.  If  prefix  8  is  valid,  the  routines  use  that  path.  If  not,  they  check  prefix  0.  If 
prefix  0  is  valid,  the  routines  copy  it  to  prefix  8,  then  use  it.  If  prefix  0  is  also  invalid, 
the  search  continues  to  the  next  volume. 

Anytime  the  user  changes  the  pathname,  even  during  a  cancelled  Standard  File  dialog, 
the  new  padi  is  placed  in  prefbc  8.  In  addition,  this  current  path  is  placed  into  prefix  0, 
if  it  fits.  If  the  path  will  not  fit,  prefix  0  is  left  unchanged  and  contains  the  last 
legitimate  pathname  entered. 

Internally,  both  old  and  new  Standard  File  calls  use  prefix  8,  allowing  up  to  508 
characters  in  the  pathname.  However,  the  Standard  File  Operations  Tool  Set  will 
display  a  warning  if,  as  a  result  of  an  old  call,  a  pathname  longer  than  64  characters  will 
be  created. 
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m  The  Standard  File  Operations  Tool  Set  now  scans  AppieShare  volumes  every  eight 
seconds  for  changes.  The  system  automatically  updates  the  displayed  file  list. 

■  The  Standard  File  Operations  Tool  Set  now  returns  error  codes.  For  many  internal 
errors,  the  Standard  File  Operations  Tool  Set  will  display  a  detailed  information  dialog 
and  allow  the  user  to  cancel  the  operation. 

■  When  displaying  a  complete  path,  the  system  now  uses  the  separator  character  found 
in  either  prefix  8  or  0.  Previously,  the  separator  was  always  /,  but  now  typically  will  be 
a  colon  ( : ). 

■  The  system  now  disables  the  Save  and  NewFolder  buttons  in  Put  dialogs  referencing 
write-protected  volumes.  In  addition,  the  system  will  now  display  a  lock  icon  for  such 
volumes. 

■  The  Standard  File  Operations  Tool  Set  now  supports  multiple  file  Get  calls.  See  "New 
Standard  File  calls"  later  in  this  chapter  for  call  syntax  details. 

Multifile  dialogs  include  a  new  Accept  button  in  addition  to  the  Open  button.  These 
buttons  operate  as  follows: 

□  When  the  user  has  selected  a  single  file,  both  the  Open  and  Accept  buttons  are 
enabled.  If  the  selected  file  is  not  a  folder,  clicking  either  button  will  return  the 
filename.  If  the  file  is  a  folder,  clicking  Open  lists  the  folder  contents,  while 
clicking  Accept  returns  the  folder  name  to  the  calling  program.  Double-clicking  on  a 
file  works  the  same  as  Accept;  double-clicking  on  a  folder  works  the  same  as  Open. 

□  When  the  user  has  selected  multiple  files,  the  Open  button  is  disabled.  The  user 
must  press  the  Accept  button  to  return  the  filenames  to  the  calling  application.  In 
this  case,  the  returned  file  list  may  contain  both  folder  and  file  names.  Double- 
clicking  is  not  allowed  when  multiple  files  have  been  selected. 

■  The  Standard  File  Operations  Tool  Set  now  uses  static  text  items  in  its  dialog 
templates.  The  system  will  automatically  change  custom  dialog  templates  to  use  static 
text,  rather  than  user  items.  In  addition,  the  system  now  uses  a  custom  draw  routine 
for  the  path  entry  item.  The  system  automatically  changes  input  dialog  templates  to 
call  the  Standard  File  Operations  Tool  Set's  custom  draw  routine,  unless  the  input 
template  already  references  a  custom  routine,  in  which  case  that  reference  is  not 
changed. 

■  Your  application  can  now  provide  custom  draw  routines  for  items  in  displayed  file 
lists.  The  Standard  File  Operations  Tool  Set  takes  care  of  dimming  and  selecting  the 
item. 
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Standard  File  dialogs  support  the  following  keystroke  equivalents: 


Key 


Button  Equivalent 


Esc 

Command-Up  Arrow 
Tab 

Command-period 

Command-o 

Command-0 

Command-Down  Arrow 

Command-n 

Command-N 


Close 

Close 

Volume 

Cancel 

Open 

Open 

Open 

New  Folder 

New  Folder 


New  filter  procedure  entry  interface 

Many  Standard  File  calls  allow  you  to  specify  a  custom  filter  procedure.  These  custom 
routines  can  perform  specific  checking  of  items  for  file  list  inclusion,  beyond  that 
performed  by  the  system.  To  learn  more  about  Standard  File  filter  procedures,  see 
Chapter  22,  "Standard  File  Operations  Tool  Set,"  in  Volume  2  of  the  Toolbox  Reference. 

The  new  Standard  File  calls  support  a  different  filter  procedure  entry  interface.  Previously, 
Standard  File  filter  procedures  received  a  pointer  to  a  file  directory  entry  (defined  in  the 
Toolbox  Reference).  New  Standard  File  calls  pass  a  pointer  to  a  GetDirEntry  record, 
which  corresponds  to  the  formatted  output  of  the  GS/OS  GetDirEntry  call.  For  the 
format  and  content  of  the  GetDirEntry  record,  refer  to  Volume  1  of  the  GS/OS 
Reference. 

The  exit  interface  from  these  filter  procedures  has  not  changed.  Your  program  must 
remove  this  pointer  from  the  stack  and  return  a  response  word  indicating  how  the  current 
file  is  to  be  displayed  in  the  file  list. 


Value  Name  Description  

0  noDisplay  Do  not  display  file 

1  noseiect  Display  the  file,  but  do  not  allow  the  user  to 

select  it 

2  dispiaySeiect        Display  the  file  and  allow  the  user  to  select  it 
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Custom  item  drawing  routines 


-   memRectPtr  - 


memberPtr  — 


Some  new  Standard  File  calls  allow  you  to  specify  custom  item-drawing  routines.  These 
routines  give  you  the  opportunity  to  create  highly  customized  displays  of  items  in  file 
lists.  The  Standard  File  Operations  Tool  Set  handles  item  dimming  and  selecting. 

On  entry  to  the  custom  item  drawing  routine,  Standard  File  formats  the  stack  as  follows: 
Previous  contents 

Long— Pointer  to  the  member  rectangle 

Long— Pointer  to  the  member  record 

Long— Handle  to  the  list  control 

Block— Reserved  data  for  Standard  File— 24  bytes 

Long— Pointer  to  item  draw  record 

Block— RTL  address— 3  bytes 
<— SP 

The  itemDrawPtri'idd.  contains  a  pointer  to  a  record  formatted  as  follows: 


controlHndl  - 


Reserved 


-  itemDrawPtr  - 


returnAddr 


$00 
$01 


count  + 1 
count +  3 


Byte— Length  of  nameString,  in  bytes 


nameString        :  Array— a)M«/ bytes  of  file  name 
Word— File  type 

f  ileAuxType      -|  Long— Auxiliary  file  type 


f ileType 


The  routine  must  remove  this  pointer  from  the  stack  before  returning  to  the  Standard  File 
Operations  Tool  Set.  The  custom  item  drawing  routine  should  not  change  any  of  the  other 
information  on  the  stack. 
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The  custom  drawing  routine  must  draw  both  the  filename  string  and  any  associated  icon. 
The  Standard  File  Operations  Tool  Set  assumes  that  the  standard  system  font  and 
character  size  are  used  for  all  list  items;  changing  either  font  or  character  size  is  not 
recommended.  Note  that  any  icons  must  also  comply  with  these  restrictions  (current 
icons  are  eight  lines  high). 


Standard  FHe  data  structures 

The  new  Standard  File  tool  calls  accept  and  return  new  style  reply  records  and  type  lists. 
The  formats  for  these  records  follow. 

Reply  record 

Figure  48-1  defines  the  layout  for  the  new-style  Standard  File  reply  record.  You  pass  this 
record  to  many  of  the  new  tool  calls.  Those  calls,  in  turn,  update  the  record  and  return  it  to 
your  program. 

■   Figure  48-1     New-style  reply  record 


$00 

good 

Word 

$02 

type 

Word 

$04 

auxType 

Long 

$08 

nameRefDesc 

Word 

$0A 

nameRef 

Long 

$0E 

pathRefDesc 

Word 

$10 

pathRef 

Long 
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good 

type 

auxType 

nameRefDesc 

$0000 
$0001 
$0003 


nameRef 


pathRefDesc 

$0000 
$0001 
$0003 


pathRef 


Boolean  indicating  the  status  of  tlie  request.  TRUE  indicates  that  the 
user  opened  the  file;  FALSE  indicates  that  the  user  cancelled  the 
request. 

Contains  the  GS/OS  file  type  information. 

Contains  the  GS/OS  auxiliary  type  information, 

Defines  the  type  of  reference  stored  in  nameRef  (your  program  must 
set  this  field): 

Reference  in  nameRef  is  a  pointer  to  a  GS/OS  class  1  output 
string. 

Reference  in  nameRef  is  a  handle  to  a  GS/OS  class  1  output 
string. 

Reference  in  nameRef  is  undefined.  The  system  will  allocate  a 
new  handle,  correctly  sized  for  the  resulting  GS/OS  class  1  output 
string,  and  retum  that  handle  in  nameRef.  This  is  the 
recommended  option. 

On  input,  may  contain  a  reference  to  the  output  buffer  for  the 
filename  string,  depending  upon  the  contents  of  nameRefDesc.  On 
output,  contains  a  reference  to  the  filename  string.  The  reference  type 
is  defined  by  the  contents  of  nameRefDesc.  If  your  program  set 
nameRefDesc  to  $0003,  then  your  program  must  release  the  resulting 
handle  when  it  is  done  with  the  returned  data. 

Defines  the  type  of  reference  stored  in  pathRef  (your  program  must  set 
this  field): 

Reference  in  pathRef  is  a  pointer  to  a  GS/OS  class  1  output 
string. 

Reference  in  pathRef  is  a  handle  to  a  GS/OS  class  1  output 
string. 

Reference  in  pathRef  is  undefined.  The  system  will  allocate  a 
new  handle,  correctly  sized  for  the  resulting  GS/OS  class  1  output 
string,  and  retum  that  handle  in  pathRef.  This  is  the 
recommended  option. 

On  input,  may  contain  a  reference  to  the  output  buffer  for  the  file 
pathname  string,  depending  upon  the  contents  of  pathRefDesc,  On 
output,  contains  a  reference  to  the  pathname  string.  The  reference 
type  is  defined  by  the  contents  of  pathRefDesc.  If  your  program 
set  pathRefDesc  to  $0003,  then  your  program  must  release  the 
resulting  handle  when  it  is  done  with  the  returned  data. 
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Multifile  reply  record 

Figure  48-2  defines  the  format  of  the  Standard  File  multifile  reply  record.  The  system 
returns  this  record  format  in  response  to  multifile  Get  requests. 


■   Figure  48-2     Multifile  reply  record 


$00 

good 

Word 

$02 

namesHandle 

Long 

good  Contains  either  the  number  of  files  selected,  or  FALSE  if  the  user 

cancelled  the  request. 

namesHandle     Handle  to  the  returned  data  record.  Your  program  must  dispose  of 
this  handle  when  it  is  done  with  the  returned  data.  The  returned  data 
record  is  formatted  as  follows: 


$00 

bufferLength  — 

$02 

■       fileEntryArray       ■  Array 

i  i 


bufferLength   Contains  the  total  length,  in  bytes,  of  the  returned  data  record, 
including  the  length  of  bufferLength. 
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f  ileEntryArray 

An  array  of  file  entries,  each  formatted  as  follows: 


$00 

—           flleType  — 

Word 

$02 

$06 

—        auxFlleType  — 

Long 

nameLength 

Byte 

$07 

pref ixl 

Byte 

$08 

pref 1x2 

Byte 

$09 

name  •  Array 

 i 


f ileType 

auxFileType 

nameLength 

pref ixl 

pref ix2 

name 


Contains  the  GS/OS  file  type. 

Contains  the  GS/OS  auxiliary  type. 

Contains  the  length  of  the  following  filename,  including 
the  volume  prefix  bytes  (pref  ixi  and  pref  ix2). 

Volume  prefix  for  the  pathname,  first  byte.  Always  set 
to  8. 

Volume  prefix  for  the  pathname,  second  byte.  Always 
set  to  :. 

Filename  string,  containing  (nameLength  -  2)  bytes  of 
data,  not  to  exceed  253  characters. 


File  type  list  record 

Figure  48-3  shows  the  layout  of  the  Standard  File  type  list  record.  You  use  this  record  with 
Standard  File  calls  that  require  a  file  type  list  as  input  (such  as  SFGetFiie2). 
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■   Figure  48-3     File  type  list  record 


$00 

—  entryCount 

$02 

ent ryArray 

Word 
Array 


entryCount        Contains  the  number  of  items  in  entryArray. 

ent  ryArray      Array  of  file  type  entries,  each  formatted  as  follows: 


Word 
Word 

Long 


$00 
$02 

flags 

f lleType 

$04 

auxFlleType 
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flags  Defines  how  the  system  is  to  use  f  iiexype  and  auxFiieType 

when  selecting  files  to  be  displayed: 

bit  15  Controls  whether  Standard  File  cares  about 

auxiliary  types: 

1  -  Match  any  auxFiieType  value 

0  -  Match  only  the  specified  auxFiieType 
value 

bit  14  Controls  whether  Standard  File  cares  about  file 

types: 

1  -  Match  any  f  iieType 

0  -  Match  only  the  specified  f  iieType  value 

bit  13  Disable  selection: 

1  -  Any  files  matching  criteria  specified  in  bits 
14  and  15  wiO  be  displayed  but  will  not  be 
selectable  (will  be  greyed  out).  Note  that  the 
file(s)  will  not  be  passed  to  the  filter  procedure 
for  the  tool  call. 

bits  12-0        Reserved;  must  be  set  to  0. 

♦  Note:  The  settings  of  bits  14  and  15  are  independent.  By  setting  both  bits  to  1,  The 
Standard  File  Operations  Tool  Set  will  match  all  files. 

f  iieType         Specifies  a  GS/OS  file  type  value  to  match,  according  to  the 
settings  of  the  flags  bits.  If  bit  15  of  flags  is  set  to  0,  then 
this  field  is  ignored. 

auxFiieType     Specifies  a  GS/OS  auxiliary  type  value  to  match,  according  to 
the  settings  of  the  flags  bits.  If  bit  14  of  flags  is  set  to  0, 
then  this  field  is  ignored. 
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Standard  File  dialog  templates 

The  Standard  File  Operations  Tool  Set  allows  you  to  define  custom  dialog  boxes  for  the 
Open  File  and  Save  File  dialog  boxes.  To  use  a  custom  dialog  box,  your  program  must 
provide  a  pointer  to  a  dialog  template  to  the  appropriate  Standard  File  routines 
(sFPPutFiie2,  SFPGetFiie2,  or  SFPMuitiFiie2).  The  Standard  File  Operations 
Tool  Set  passes  the  dialog  template  to  the  Dialog  Manager  (GetNewModaiDiaiog  call) 
when  it  establishes  the  user  dialog. 

While  the  latest  version  of  the  Standard  File  Operations  Tool  Set  uses  some  of  the 
template  fields  differently,  old  templates  should  still  work.  The  system  internally  modifies 
old-style  input  templates  to  make  them  compatible  with  current  usage.  New  usage  differs 
in  the  following  ways: 

■  The  boundary  rectangle  for  a  file  list  is  taken  from  the  Files  item  in  each  dialog 
template  and  copied  to  the  List  Manager  record.  The  number  of  files  to  be  displayed  is 
derived  from  the  rectangle  coordinates  by  subtracting  2  from  the  height  and  dividing 
the  result  by  10.  To  avoid  displaying  partial  filenames,  you  should  set  the  rectangle 
height  using  the  same  formula;  that  is,  height=((num_files  *  10)  +  2). 

■  The  Scroll  item  is  no  longer  used  for  single-file  requests.  However,  it  has  been  retained 
in  the  record  for  compatibility  with  old  templates.  For  multifile  Get  requests,  the  new 
tool  calls  define  the  Accept  button  in  the  space  previously  used  by  the  Scroll  item. 

■  Standard  File  calls  copy  the  input  dialog  template  header  to  memory  and  then  update 
it.  Note  that,  for  single-file  Get  calls,  items  5  and  7  are  not  copied  (for  multifile  Get 
calls,  item  5  is  copied).  Similarly,  items  6  and  8  are  not  copied  for  Put  calls. 

The  following  code  examples  contain  the  templates  for  the  standard  Open  File  and  Save 
File  dialog  boxes.  All  these  templates  depend  upon  the  following  string  definitions: 


SaveStr 

str 

' Save' 

OpenStr 

str 

" Open ' 

CloseStr 

Str 

'Close' 

DriveStr 

str 

'Volvime' 

CancelStr 

str 

'Cancel' 

FolderStr 

str 

'New  Folder' 

AcceptStr 

str 

'Accept ' 

KbFreeStr 

str 

'^0  free  of 

'^l  k.  '             /Dialog  Manager  routine 

;   replaces  '^0  &  ^1  with  real 

;  values  from  the  disk. 

PPromptStr 

dc.b 

'Save  which  file: 

1 

PEndBuf 

dc.b 

0 

;end-of -string  byte 

GPromptStr 

dc.b 

'Load  which  file: 

GEndBuf 

dc.b 

0 

;end-of -string  byte 
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Open  File  dialog  box  templates 


The  Open  File  dialog  box  must  contain  the  following  items  in  this  exact  order; 


Item 

Item  type 

Item  ID 

Open  button 

buttonltem 

1 

Close  button 

buttonltem 

2 

Next  button 

buttonltem 

3 

Cancel  button 

buttonltem 

4 

Scroll  bar 

use rItem+itemDi sable 

5 

Path 

userltem 

6 

Files 

userltem+itemDi sable 

7 

Prompt 

userltem 

8 

♦  Note:  The  Scroll  bar  item  (item  5)  is  not  used  for  single-file  calls.  For  multifile  calls,  this 
item  contains  the  Accept  button  definition. 

♦  Note:  The  Files  item  (item  7)  contains  the  boundary  rectangle  for  the  List  Manager, 
and  serves  no  other  purpose. 

First,  the  templates  for  640  mode: 

GetDialog64  0 

dew  0,0,114,400 

dew  -1 

do. w  0,0 

del  OpenBut640 

del  CloseBut640 

del  NextBut64  0 

del  CancelBut640 

del  Scroll640 

del  Path640 

del  Files640 

del  Prompt640 

del  0 


;  recommended  drect  of  dialog 
(64  0  mode) 

;  reserved  words 

;  item  1 

;  item  2 ■ 

;  item  3 

;  item  4 

;  dummy  item  or  ACCEPT  button 

;  item  6 

;  item  7 

;  item  8 
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OpenBut640 
dew 
dew 
dew 
del 
dew 
del 

CloseBut640 
dew 
dew 
dew 
del 
dew 
del 

NextBut640 
dew 
dew 
dew 
del 
dew 
del 

CancelBut640 
dew 
dew 
dew 
del 
dew 
del 


1  ; item  # 

61,265,73,375  ;drect 

Buttonltem  ;type  of  item 

OpenStr  ; Item  descriptor 

0,0  /Item  value  &  bit  flags 

0  /color  table  ptr   (nil  is  default) 


2  / item  # 

79,265,91,375  /drect 

Buttonltem  /type  of  item 

CloseStr  /Item  descriptor 

0,0  /Item  value  &  bit  flags 

0  /color  table  ptr   (nil  is  default) 


3  ; item  # 

25,265,37,375  /drect 

Buttonltem  /type  of  item 

DriveStr  /Item  descriptor 

0,0  /Item  value  &  bit  flags 

0  /color  table  ptr   (nil  is  default) 


4  / item  # 

97,265,109,375  /drect 

Buttonltem  /type  of  item 

CancelStr  /Item  descriptor 

0,0  /Item  value  &  bit  flags 

0  /color  table  ptr   (nil  is  default) 
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Scroll640 


SPECIAL  NOTE:   Scroll  items  are  no  longer  used  by  the  new  calls,  since 
the  List  Manager  takes  care  of  all  scroll  "stuff".   In  single-file 
Get  calls   (also  any  OLD  call),  this  item  is  simply  ignored  and  its 
pointer  is  left  out  of  the  header  when  copied  to  RAM.  However,  in 
Multi-Get  calls,  this  item  IS  used  for  the  Accept  button.  The 
following  is  the  recommended  content  for  the  Accept  button: 


dew  5 

dew  43,265,55,375 

dew  Buttonltem 

del  AcceptStr 

dc. w  0,0 

del  0 


;item  #    (DUMMY  or  ACCEPT  button) 
; drect 
;  type 

; Item  descriptor 

;Item  value  and  bit  flags 

/color  table 


Path640 

dew 
dew 
dew 
del 

specific) 
dew 
del 


12,15,24,395 

Userltem 

PathDraw 

0,0 
0 


; item  # 
; drect 
;  type 

;Item  descriptor   (user  app. 


; Item  value  and  bit  flags 
/color  table 


Files640 

dew  7 

dew  25,18,107,215 

dew  Userltem+ItemDisable 

del  0 

dc. w  0,0 

del  0 


/ item  # 

/Boundary  rect  for  List  Manager 
/  type 

/Item  descriptor 

/ Item  value  and  bit  flags 

/color  table 


Prompt 640 

dc. w  8  / item  # 

dew  03,15,12,395  /drect 

dew  StatText+ItemDisable  /type 

del  0  /Item  descriptor   (Text  passed) 

dew  0  /size  of  text 

dew  0  ;Bit  flags 

del  0  /color  table 
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Now,  the  templates  for  320  mode: 
GetDialog320 


dew  0,0,114,260 

dew  -1 

dc . w  0,0 

del  OpenBut320 

del  CloseBut320 

del  NextBut320 

del  CancelBut320 

del  Scroll320 

del  Path320 

del  Files320 

del  Prompt320 

del  0 


drect  of  dialog   (320  mode) 

reserved  word 
item  1 
item  2 
item  3 
item  4 

dummy  item  or  ACCEPT  button 
item  6 
item  7 
item  8 


OpenBut320 
dew 
dew 
dew 
del 
dew 
del 


53,160, 65,255 

Buttonltem 

OpenStr 

0,0 

0 


; item  # 
; drect 

;type  of  item 

; Item  descriptor 

; Item  value  &  bit  flags 

/color  table  ptr   (nil  is  default) 


CloseBut320 
dew 
dew 
dew 
del 
dew 
del 


71,160, 83,255 

Buttonltem 

CloseStr 

0,  0 

0 


;item  # 
; drect 

;type  of  item 

/Item  descriptor 

/Item  value  &  bit  flags 

/color  table  ptr   (nil  is  default) 


NextBut320 
dew 
dew 
dew 
del 
dew 
del 


27,160,39,255 

Buttonltem 

DriveStr 

0,  0 

0 


/item  # 
/ drect 

/ type  of  item 

/Item  descriptor 

/ Item  value  &  bit  flags 

/color  table  ptr   (nil  is  default) 
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CancelBut320 
dew 
dew 
dew 
del 
dew 
del 


97,160,109,255 

Buttonltem 

CancelStr 

0,0 

0 


; item  # 
; drect 

;type  of  item 

/Item  descriptor 

; Item  value  &  bit  flags 

; color  table  ptr   (nil  is  default) 


Scroll320 

SPECIAL  NOTE:   Scroll  items  are  no  longer  used  by  the  new  calls,  since 
the  List  Manager  takes  care  of  all  scroll  "stuff".   In  single-file 
Get  calls    (also  any  OLD  call) ,   this  item  is  simply  ignored  and  its 
pointer  is  left  out  of  the  header  when  copied  to  RAM.  However,  in 
Multi-Get  calls,   this  item  IS  used  for  the  Accept  button.  The 
following  is  the  recommended  content  for  the  Accept  button: 


dew  5 

dew  118,  160,130,255 

dew  Buttonltem 

del  AcceptStr 

de  w  0,0 

del  0 


;item  #   (see  SPECIAL  NOTE) 
; drect 
;  type 

; Item  descriptor 

/Item  value  and  bit  flags 

/ color  table 


Path320 

dew  6 

dew  14,  06,26,256 

dew  Userltem 

del  PathDraw 

de  w  0,0 

del  0 


/ item  # 
/ drect 
;  type 

/ Item  descriptor 

/Item  value  and  bit  flags 

/ color  table 


Files320 

dew  7 

dew  27,  05,109,140 

dew  Userltem+ItemDisable 

del  0 

de  w  0,0 

del  0 


/ item  # 

/Boundary  rect  for  list  manager 
;  type 

/Item  descriptor 

/Item  value  and  bit  flags 

/color  table 
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Prompt320 


dc 

.  w 

8 

; item  # 

dc 

.  w 

03,05,12,255 

; drect 

dc 

.  w 

StatText+ItemDisable 

;  type 

dc 

.1 

0 

; Item  descriptor 

(Text  passed) 

dc 

.  w 

0 

;size  of  string 

dc 

.  w 

0 

;Bit  flags 

dc 

.1 

0 

/color  table   (0  = 

default) 
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Save  File  dialog  box  templates 


The  Save  File  dialog  box  must  contain  the  following  items  in  this  exact  order: 


Item 

Item  type 

Item  ID 

Save  button 

buttonltem 

1 

Open  button 

buttonltem 

2 

Close  button 

buttonltem 

3 

Next  button 

buttonltem 

4 

Cancel  button 

buttonltem 

5 

Scroll  bar 

user Item+itemDi sable 

6 

Path 

userltem 

7 

Files 

user Item+itemDi sable 

8 

Prompt 

userltem 

9 

Filename 

editltem 

10 

Free  space 

statText 

11 

Create  button 

buttonltem 

12 

♦  Note:  The  Scroll  bar  item  (item  6)  is  not  used  for  single-file  calls. 


♦  Note:  The  Files  item  (item  8)  contains  the  boundary  rectangle  for  the  List  Manager, 
and  serves  no  other  purpose. 
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First,  the  templates  for  640  mode: 
PutDialog640 


dew  0,0,120,320 


dew 
dew 
del 
del 
del 
del 
del 
del 
de 
de 
de 
de 
de 
de 
de 


.1 
,1 
,1 
,1 
.1 
,1 
.1 


-1 
0,0 

SaveButP640 

OpenButP640 

CloseButP640 

NextButP640 

CancelButP640 

ScrollP640 

PathP640 

FilesP640 

PromptP640 

EditP640 

StatTextP640 

CreateButP640 

0 


reconnmended  drect  of  dialog 
(640  mode) 

reserved  word 
item  1 
item  2 
item  3 
item  4 
item  5 
DUMMY  item 
item  7 

contains  boundary  rect  only- 
item  9 
item  10 
item  11 
item  12 


SaveButP640 
dew 
dew 
dew 
de  1 
dew 
del 


87,204,99,310 

Buttonltem 

SaveStr 

0,0 

0 


; item  # 
; drect 

;type  of  item 

;Item  descriptor 

; Item  value  &  bit  flags 

; color  table  ptr   (nil  is  default) 


OpenButP640 
dew 
dew 
dew 
del 
dew 
del 


49,204,61,310 

Buttonltem 

OpenStr 

0,0 

0 


; item  # 
; drect 

;type  of  item 

; Item  descriptor 

; Item  value  &  bit  flags 

; color  table  ptr   (nil  is  default) 
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CloseButP640 
dew 
dew 
dc .  w 
del 
dew 
del 


64,204,76,310 

Buttonltem 

CloseStr 

0,0 

0 


; item  # 
; drect 

; type  of  item 

/Item  descriptor 

; Item  value  &  bit  flags 

; color  table  ptr   (nil  is  default) 


NextButP640 
dew 
dew 
dew 
del 
dc .  w 
del 


15,204,27,310 
Buttonltem 
DriveStr 
0,0 

0 


; item  # 
; drect 

;type  of  item 

; Item  descriptor 

; Item  value  &  bit  flags 

/color  table  ptr   (nil  is  default) 


CancelButP640 
dc .  w 
dc .  w 
dew 
del 
dew 
del 


104,204,116,310 

Buttonltem 

CancelStr 

0,0 

0 


/ item  # 
/ drect 

/ type  of  item 

/Item  descriptor 

/Item  value  &  bit  flags 

/color  table  ptr   (nil  is  default) 


ScrollP640 

Special  Note:  Unlike  Scroll  item  in  Get,   Scroll  is  never  used 
in  Put,   since  there  is  not  Multifile  Put  call. 


dew 
dew 
dew 
del 
dc .  w 
del 


0,0,0,0 

Userltem 

0 

0,  0 

0 


/ item  #   (Dummy  item) 
/dummy  drect    (must  be  0) 
/  type 

/Item  descriptor 

/Item  value  and  bit  flags 

/color  table 
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PathP640 

dew 
dew 
dew 
del 
dew 
del 


0,10,12,315 

Userltem 

PathDraw 

0,0 

0 


/item  # 
; drect 
;  type 

; Item  descriptor   (user  app . specif ic) 
; Item  value  and  bit  flags 
; color  table 


FilesP640 

dew  8 

dew  26,10,  88,170 

dew  Userltem+ItemDisable 

del  0 

de  w  0,0 

del  0 


; item  # 

/Boundary  rect  for  list  manager 
/  type 

/ Item  descriptor 

/ Item  value  and  bit  flags 

/color  table 


PromptP640 
dew 
dew 
dew 
del 
dew 
dew 
del 


88,10,100,200 

StatText+ItemDisable 

0 

0 

0 

0 


/item  # 
/ drect 
;  type 

/Item  descriptor 

/size  of  text   (Text  passed) 

/Bit  flags 

/color  table 


EditP640 

dew  10 '  /item  # 

dew  100,10,118,194  /drect 

dew  EditLine+ItemDisable  /type 

del  0  /Item  descriptor 

dew  63  /size  of  text 

dew  0  ;Bit  flags 

del  0  /color  table 
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StatTextP64  0 

dew  11  ;item  # 

dew  12,10,22,200  ;drect 

dew  StatText+ItemDisable  ;type 

del  KbFreeStr  ;Item  descriptor 

dew  0  ;size  of  text 

dew  0  ;Bit  flags 

del  0  /color  table 


CreateButP640 
dc .  w 
dew 
dew 
del 
dew 
dew 
del 


12 

29,204,41,310 

Buttonltem 

FolderStr 

0 

0 

0 


Now,  the  templates  for  320  mode: 


; item  # 
; drect 
;  type 

/Item  descriptor 
;size  of  text 
;Bit  flags 
; color  table 


PutDialog320 


de 

w 

0,0, 128,270 

•  drect  of  dialog  (320  mode) 

dc . 

w 

-1 

de 

w 

0,0 

•   reserved  word 

de 

1 

SaveButP320 

•   item  1 

dc. 

1 

OpenButP320 

•   item  2 

dc. 

1 

CloseButP320 

item  3 

dc. 

1 

NextButP320 

item  4 

dc. 

1 

CancelButP320 

item  5 

dc. 

1 

ScrollP320 

DUM^4Y  item 

dc. 

1 

PathP320 

item  7 

de 

1 

FilesP320 

contains  Boundary  rect 

dc. 

1 

PromptP320 

item  9 

dc. 

1 

EditP320 

item  10 

de 

1 

StatTextP320 

item  11 

dc. 

1 

CreateButP320 

item  12 

dc. 

1 

0 
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SaveButP320 
dew 
dew 
dew 
del 
dc .  w 
del 

OpenButP320 
dew 
dew 
dew 
del 
dew 
del 

CloseButP320 
dc .  w 
dew 
dew 
del 
dew 
del 

NextButP320 
dew 
dew 
dew 
del 
dew 
del 

CancelButP320 
dew 
dew 
dew 
del 
dew 
del 


1  ; item  # 

93,165,105,265  ;drect 

Buttonltem  ;type  of  item 

SaveStr  ; Item  descriptor 

0,0  ; Item  value  &  bit  flags 

0  ; color  table  ptr   (nil  is  default) 


2  ;item  # 

54,165,66,265  ;drect 

Buttonltem  ;type  of  item 

OpenStr  ;Item  descriptor 

0,0  ;Item  value  &  bit  flags 

0  /color  table  ptr   (nil  is  default) 


3  ; item  # 

72,165,84,265  ;drect 

Buttonltem  ;type  of  item 

CloseStr  ;Item  descriptor 

0,0  ; Item  value  &  bit  flags 

0  /color  table  ptr   (nil  is  default) 


4  ; item  # 

15,165,27,265  ;drect 

Buttonltem  ;type  of  item 

DriveStr  ; Item  descriptor 

0,0  ;Item  value  &  bit  flags 

0  /color  table  ptr   (nil  is  default) 


5  / item  # 

111,165,123,265  /drect 

Buttonltem  /type  of  item 

CancelStr  /Item  descriptor 

0,0  /Item  value  &  bit  flags 

0  /color  table  ptr   (nil  is  default) 


48-24    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


ScrollP320 

;   Special  Note:  Unlike  Scroll 
in  Put,   since  there  is  not 

dew  6 

dew  00,  00,  00,  00 

dew  Userltem 

del  0 

do. w  0,0 

del  0 


item  in  Get,   Scroll  is  never  used 
ifile  Put  call. 

; item  #    (Dummy  item) 
; drect 
;  type 

; Item  descriptor 
; Item  value  and  bit  flags 
/color  table 


PathP320 

dew  7 

dew  00,10,12,265 

dew  Userltem 

del  PathDraw 

dc. w  0,0 

del  0 


; item  # 
; drect 
;  type 

; Item  descriptor 

;Item  value  and  bit  flags 

; color  table 


FilesP320 
dew 
dew 
dew 
del 
dc .  w 
del 


26,10, 88,145 

Userltem+ItemDisable 

0 

0,0 
0 


; item  # 

/Boundary  rect  for  list  manager 
/  type 

/Item  descriptor 

/Item  value  and  bit  flags 

/color  table 


PromptP320 
dew 
dew 
dew 
del 
dew 
dew 
del 


88,10,100,170 

StatText+ItemDisable 

0 

0 

0 

0 


/ item  # 
/ drect 
/  type 

/Item  descriptor   (Text  passed) 

/Bit  flags 
/color  table 
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EditP320 

dew 
dew 
dew 
del 
dew 
dew 
del 


10 

100,10,118,157 

EditLine+ItemDisable 

0 

32 

0 

0 


; item  # 
; drect 
;  type 

;ltem  descriptor 
;size  of  text 
;Bit  flags 
/color  table 


StatTextP320 
dew 
dew 
dew 
del 
dew 
dew 
del 


11 

12,10,22,160 

StatText+ItemDisable 

KbFreeStr 

0 

0 

0 


; item  # 
; drect 
;  type 

; Item  descriptor 
;size  of  text 
;Bit  flags 
; color  table 


CreateButP320 
dew 
dew 
dew 
del 
dew 
dew 
del 


12 

33,165,45,265 

Buttonltem 

FolderStr 

0 

0 

0 


;item  # 
; drect 
;  type 

;Item  descriptor 
;size  of  text 
;Bit  flags 
; color  table 
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New  or  changed  Standard  File  calls 

The  following  sections  discuss  several  new  or  changed  Standard  File  tool  calls. 


SFAllCaps  $0D17 

This  call  has  been  disabled  in  order  to  show  filenames  exactly  as  entered.  Existing 
programs  may  still  issue  the  call,  but  it  will  have  no  effect. 

Parameters 

Stack  before  call 


Previous  contents 


allCapsFlag 


Word— Not  used 
<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 


<— SP 
None 

extern  pascal  void  SFAllCaps (allCapsFlag) 
Word  allCapsFlag; 
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SFGetFile2  $0E17 


Displays  the  standard  Open  File  dialog  box  and  returns  information  about  the  file  selected 
by  the  user.  This  all  differs  from  SFGetFiie  in  that  it  uses  Class  1  GS/OS  calls,  thereby 
allowing  selection  of  a  file  with  a  full  name  length  of  up  to  763  characters. 

Parameters 

Stack  before  call 


Previous  contents 


whereX 


whereY 


promptRefDesc 


promptRef  - 


-  filterProcPtr 


typelistPtr  - 


replyPtr 


Word— X  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 
Word— Defines  type  of  reference  in  promptRef 

Long — Reference  to  Pascal  string  for  file  prompt 

Long— Pointer  to  filter  procedure;  NIL  for  none 

Long— Pointer  to  type  list  record;  NIL  for  none 

Long— Pointer  to  new-style  reply  record 
<— SP 


Stack  after  call 


Previous  contents 

Errors  $1701 
$1704 

$1705 


<— SP 

badPromptDesc 
badReplyNameDesc 

badReplyPathDesc 


Invalid  promptRefDesc  value 
Invalid  reply  record 
nameRefDesc  value 
Invalid  reply  record 
pathRef  Desc  value 
Returned  unchanged 


GS/OS  errors 


♦  Note:  The  GS/OS  buf  f  erTooSmaii  error  can  occur  if  the  output  strings  you  supply 
in  the  reply  record  are  too  small  to  receive  the  resulting  filename  string.  In  this  case, 
the  buffer  will  contain  as  many  name  characters  as  would  fit,  and  the  length  word  will 
contain  the  name  length  the  Standard  File  Operations  Tool  Set  tried  to  return. 
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promptRejDes 

$0000 
$0001 
$0002 

filterProcPtr 


extern  pascal  void  SFGetFile2 (whereX,  whereY, 

promptRefDesc,  promptRef,  filterProcPtr, 
typelistPtr,   replyPtr) ; 

Pointer       filterProcPtr,   typelistPtr,  replyPtr; 


Defines  the  type  of  reference  in  promptRef. 

Reference  in  promptRef  is  a  pointer  to  a  Pascal  string. 
Reference  in  promptRef  is  a  handle  of  a  Pascal  string. 
Reference  in  promptRef  is  the  resource  ID  of  a  Pascal  string 

Pointer  to  a  new-style  filter  procedure,  as  described  in  "New  filter 
procedure  entry  interface"  earlier  in  this  chapter. 


Word 


Long 


whereX,  whereY,  promptRefDesc; 
promptRef; 
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SFMultiGet2  $1417 

Displays  the  standard  Open  Multifile  dialog  box  and  returns  information  about  the  file  or 
files  selected  by  the  user.  The  all  returns  file  selection  information  in  a  multifile  reply 
record.  Note  that  folders  may  be  included  in  the  list  of  returned  files;  your  program  should 
check  the  file  type  field  before  using  any  returned  filenames. 

Parameters 

Stack  before  call 


Previous  contents 


whereX 


whereY 


promptRefDesc 


promptRef  - 


-  filterProcPtr  - 


typelistPtr  - 


replyPtr 


Stack  after  call 


Word— X  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 
Word— Defines  type  of  reference  in  promptRef 
Long— Reference  to  Pascal  string  for  file  prompt 

Long— Pointer  to  filter  procedure;  NIL  for  none 
Long— Pointer  to  type  list  record;  NIL  for  none 
Long— Pointer  to  multifile  reply  record 
<— SP 


Previous  contents 


Errors 
C 


$1701 


<— SP 
badPromptDesc 


Invalid  promptRefDesc  value 


extern  pascal  void  SFMultiGet2 (whereX,  whereY, 

promptRefDesc,  promptRef,  filterProcPtr, 
typelistPtr,   replyPtr) ; 

Pointer      filterProcPtr,  typelistPtr,  replyPtr; 
Word  whereX,  whereY,  promptRefDesc; 

Long  promptRef; 
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promptRefDesc     Defines  the  type  of  reference  in  promptRef. 

$0000  Reference  in  promptRef  \s  a  pointer  to  a  Pascal  string. 

$0001  Reference  in  promptRef  \s  a  handle  of  a  Pascal  string. 

$0002  Reference  in  promptRef '\s  the  resource  ID  of  a  Pascal  string 

filterProcPtr        Pointer  to  a  new-style  filter  procedure,  as  described  in  "New  filter 
procedure  entry  interface"  earlier  in  this  chapter. 
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SFPGetFile2  $1017 

Displays  a  custom  Open  File  dialog  box  and  returns  information  about  the  file  selected  by 
the  user.  This  call  differs  from  SFGetriie  in  that  it  uses  Class  1  GS/OS  calls,  thereby 
allowing  selection  of  a  file  with  a  full  name  length  of  up  to  763  characters. 

Parameters 

Stack  before  call 


Previous  contents 


tvhereX 


whereY 


-  itemDrawPtr  - 


promptReJDesc 


-    promptRef  - 


-  filterProcPtr  - 


typelistPtr  - 


-    dlgTempPtr  - 


-  dialogHookPtr  - 


replyPtr 


Stack  after  call 


Word— X  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 
Long— Pointer  to  item  draw  routine;  NIL  for  none 
Word— Defines  type  of  reference  in  promptRef 
Long— Reference  to  Pascal  string  for  file  prompt 

Long— Pointer  to  filter  procedure;  NIL  for  none 

Long— Pointer  to  type  list  record;  NIL  for  none 

Long— Pointer  to  dialog  template 

Long— Pointer  to  routine  to  handle  item  hits 

Long — Pointer  to  new-style  reply  record 
<— SP 


Previous  contents 


Errors 


$1701 
$1704 

$1705 


<— SP 

badPromptDesc 
badReplyNameDesc 

badReplyPathDesc 


GS/OS  errors 


Invalid  promptRefDesc  value 
Invalid  reply  record 
nameRefDesc  value 
Invalid  reply  record 
pathRef  Desc  value 
Returned  unchanged 
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♦  Note:  The  GS/OS  buf  f  erTooSmaii  error  can  occur  if  the  output  strings  you  supply 
in  the  reply  record  are  too  small  to  receive  the  resulting  filename  string.  In  this  case, 
the  buffer  will  contain  as  many  name  characters  as  would  fit,  and  the  length  word  will 
contain  the  name  length  the  Standard  File  Operations  Tool  Set  tried  to  return. 


C  extern  pascal  void  SFPGetFile2 (whereX,  whereY, 

itemDrawPtr,  promptRefDesc,  promptRef, 
f ilterProcPtr,  typelistPtr,  dlgTempPtr, 
dialogHookPtr,   replyPtr) ; 

Pointer      itemDrawPtr,   f ilterProcPtr,  typelistPtr, 

dlgTempPtr,  dialogHookPtr,  replyPtr; 
Word  whereX,  whereY,  promptRefDesc; 

Long  promptRef; 

itemDrawPtr       Pointer  to  a  custom  item-drawing  routine,  as  described  in  "Custom 
item  drawing  routines"  earlier  in  this  chapter. 

promptRefDesc     Defines  the  type  of  reference  in  promptRef. 

$0000  Reference  in  promptRef  is  a  pointer  to  a  Pascal  string. 

$0001  Reference  in  promptRef  is  a  handle  to  a  Pasal  string. 

$0002  Reference  in  promptRef^  the  resource  ID  to  a  Pascal  string 

filterProcPtr        Pointer  to  a  new-style  filter  procedure,  as  described  in  "New  filter 
procedure  entry  interface"  earlier  in  this  chapter. 

dlgTempPtr,  dialogHookPtr 

For  more  information  about  these  fields,  see  the  discussion  of  the 
SFPutFiie  call  in  Chapter  22,  "Standard  File  Operations  Tool  Set,"  in 
Volume  2  of  the  Toolbox  Reference. 
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SFPMultiGet2  $1517 

Displays  a  custom  Open  Multifile  dialog  box  and  returns  information  about  the  file  or  files 
selected  by  the  user.  The  call  returns  file  selection  information  in  a  multifile  reply  record. 
Note  that  folders  may  be  included  in  the  list  of  returned  files;  your  program  should  check 
the  file  type  field  before  using  any  returned  filenames. 

Parameters 

Stack  before  call 


Previous  contents 


whereX 


whereY 


-   itmDrawPtr  - 


promptRefDesc 


promptRef  - 


-  filterProcPtr  - 


typelistPtr  - 


-    dlgTempPtr  - 


-  dialogHookPtr  - 


replyPtr 


Stack  after  call 


Word— X  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 

Long— Pointer  to  item  draw  routine;  NIL  for  none 

Word— Defines  type  of  reference  in  promptRef 

Long— Reference  to  Pascal  string  for  file  prompt 

Long— Pointer  to  filter  procedure;  NIL  for  none 
Long— Pointer  to  type  list  record;  NIL  for  none 
Long— Pointer  to  dialog  template 
Long— Pointer  to  routine  to  handle  item  hits 
Long— Pointer  to  multifile  reply  record 
<— SP 


Preinous  contents 


Errors 


<— SP 

$1701  badPromptDesc 


Invalid  promptRefDesc  value 
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C  extern  pascal  void  SFPMultiGet2 (whereX,  whereY, 

iteniDrawPtr,   promptRef Desc,  promptRef, 
f ilterProcPtr,  typelistPtr,  dlgTempPtr, 
dialogHookPtr,   replyPtr) ; 

Pointer      itemDrawPtr,   f ilterProcPtr,  typelistPtr, 

dlgTempPtr,  dialogHookPtr,  replyPtr; 
Word  whereX,  whereY,  promptRef Desc; 

Long  promptRef; 

itemDrawPtr       Pointer  to  a  custom  item-drawing  routine,  as  described  in  "Custom 
item  drawing  routines"  earlier  in  this  chapter. 

promptRefDesc     Defines  the  type  of  reference  in  promptRef: 

$0000  Reference  in  promptRef  \&  a  pointer  to  a  Pascal  string. 

$0001  Reference  in  promptRef  \s  a  handle  of  a  Pascal  string. 

$0002  Reference  in  promptRef  \s  the  resource  ID  of  a  Pascal  string 

filterProcPtr        Pointer  to  a  new-style  filter  procedure,  as  described  in  "New  filter 
procedure  entry  interface"  earlier  in  this  chapter. 

dlgTempPtr,  dialogHookPtr 

For  more  information  about  these  fields,  see  the  discussion  of  the 
SFPutFiie  call  in  Chapter  22,  "Standard  File  Operations  Tool  Set,"  in 
Volume  2  of  the  Toolbox  Reference. 
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SFPPutFile2  $1117 

Displays  a  custom  Save  File  dialog  box  and  returns  information  about  the  file 
specification  entered  by  the  user.  This  call  performs  the  same  function  as  SFPPutFiie, 
but  uses  Class  1  GS/OS  calls,  allowing  the  user  to  specify  a  full  filename.  In  addition,  this 
call  does  not  support  the  maxLen  parameter  provided  in  SFPPutFiie.  This  parameter 
allowed  the  calling  program  to  limit  the  filename  length. 

Parameters 

Stack  before  call 


Previous  contents 


whereX 


whereY 


-  itemDrawPtr  - 


promptReJDesc 


promptRef  - 


origNameRefDesc 


origNameRef  - 


-    dlgTempPtr  - 


-  dialogHookPtr  - 


replyPtr 


Stack  after  call 


Word— X  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 

Long— Pointer  to  item  draw  routine;  NIL  for  none 

Word — Defines  type  of  reference  in  promptRef 

Long— Reference  to  Pascal  string  for  file  prompt 

Word— Defines  type  of  reference  in  origNameRef 

Long— Reference  to  GS/OS  Class  1  Input  String  with  default  name 

Long— Pointer  to  dialog  template 

Long— Pointer  to  routine  to  handle  item  hits 

Long— Pointer  to  new-style  reply  record 
<— SP 


Previous  contents 


-SP 
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Errors 


$1701  badPromptDesc 
$1702  badOrigNameDesc 
$1704  badReplyNameDesc 

$1705  badReplyPathDesc 

GS/OS  errors 


Invalid  promptRefDesc  value 
Invalid  origNameDesc  value 
Invalid  reply  record 
nameRef  Desc  value 
Invalid  reply  record 
pathRefDesc  value 
Returned  unchanged 


♦  Note:  The  GS/OS  bufferTooSmaii  error  can  occur  if  the  output  strings  you  supply 
in  the  Reply  record  are  too  small  to  receive  the  resulting  filename  string.  In  this  case, 
the  buffer  will  contain  as  many  name  characters  as  would  fit,  and  the  length  word  will 
contain  the  name  length  the  Standard  File  Operations  Tool  Set  tried  to  return. 


C  extern  pascal  void  SFPPutFile2 (whereX,  whereY, 

iteitiDrawPtr,  promptRefDesc,  promptRef, 
origNameRefDesc,   origNameRef ,  dlgTempPtr, 
dialogHookPtr,   replyPtr) ; 

Pointer      itertiDrawPtr,   dlgTempPtr,  dialogHookPtr, 
replyPtr; 

Word  whereX,  whereY,  promptRefDesc, 

OrigNameRefDesc; 

Long  promptRef,  origNameRef; 

itemDrawPtr       Pointer  to  a  custom  item-drawing  routine,  as  described  in  "Custom 
item  drawing  routines". 

promptRefDesc     Defines  the  type  of  reference  in  promptRef. 


$0000 
$0001 
$0002 

origNameReJDesc 

$0000 

$0001 

$0002 


Reference  in  promptRef  Is  a  pointer  to  a  Pascal  string. 
Reference  in  promptRef  is  a  handle  of  a  Pascal  string. 
Reference  in  promptRef  is  the  resource  ID  of  a  Pascal  string 

Defines  the  type  of  reference  in  origNameRef 

Reference  in  origNameRef  \s  a  pointer  to  a  GS/OS  Class  1  Input 
string. 

Reference  in  origNameRef  is  a  handle  to  a  GS/OS  Class  1  Input 
string. 

Reference  in  origNameRef  is  the  resource  ID  to  a  GS/OS  Class  1 
Input  string 
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origNameRef       Reference  to  a  GS/OS  Class  1  Input  string.  On  input  to 

SFPPutFiie2,  this  string  contains  the  default  filename  for  the  Put 
operation.  On  output,  this  string  contains  the  string  confirmed  by  the 
user,  which  may  not  be  the  same  as  the  default  value, 

dlgTempPtr,  dialogHookPtr 

For  more  information  about  these  fields,  see  the  discussion  of  the 
SFPutFiie  call  in  Chapter  22,  "Standard  File  Operations  Tool  Set,"  in 
Volume  2  of  the  Toolbox  Reference. 
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SFPutFile2  $0F17 

Displays  the  standard  Save  File  dialog  box  and  returns  the  file  specification  entered  by  the 
user.  This  call  perfornis  the  same  function  as  SFPutFiie,  but  uses  Class  1  GS/OS  calls, 
allowing  the  user  to  specify  a  full  filename.  In  addition,  this  call  does  not  support  the 
maxLen  parameter  provided  in  SFPutFiie.  This  parameter  allowed  the  calling  program 
to  limit  the  filename  length. 

Parameters 

Stack  before  call 


Previous  contents 


whereX 


whereY 


promptRe/Desc 


promptRef  - 


origNameReJDesc 


-  origNameRef  - 


replyPtr 


Stack  after  call 


Word— X  coordinate  of  upper  left  corner  of  dialog  box 
Word— y  coordinate  of  upper  left  corner  of  dialog  box 
Word— Defines  type  of  reference  in  promptRef 

Long— Reference  to  Pascal  string  for  file  prompt 

Word— Defines  type  of  reference  in  origNameRef 

Long— Reference  to  GS/OS  Class  1  Input  String  with  default  name 

Long— Pointer  to  a  new-style  reply  record 
<— SP 


Pretnous  contents 


Errors 


$1701 
$1702 
$1704 


<— SP 

badPromptDesc 

badOrigNameDesc 

badReplyNameDesc 


$1705  badReplyPathDesc 
GS/OS  errors 


Invalid  promptRefDesc  value 
Invalid  origNameDesc  value 
Invalid  reply  record 
nameRef  Desc  value 
Invalid  reply  record 
pathRef  Desc  value 
Returned  unchanged 


Chapter  48  Standard  File  Update  48-39 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


♦  Note:  The  GS/OS  buf  f  erTooSmaii  error  can  occur  if  the  output  strings  you  supply 
in  the  Reply  record  are  too  small  to  receive  the  resulting  filename  string.  In  this  case, 
the  buffer  will  contain  as  many  name  characters  as  would  fit,  and  the  length  word  will 
contain  the  name  length  the  Standard  File  Operations  Tool  Set  tried  to  return. 


C  extern  pascal  void  SFPutFile2 (whereX,  whereY, 

promptRefDesc,  promptRef,  origNameRefDesc, 
origNameRef ,   replyPtr) ; 

Pointer  replyPtr; 

Word  whereX,  whereY,  promptRefDesc, 

origNameRefDesc; 

Long  promptRef,  origNameRef; 

promptRefDesc     Defines  the  type  of  reference  in  promptRef. 

$0000  Reference  in  promptRef'^  a  pointer  to  a  Pascal  string. 

$0001  Reference  in  promptRef  is  a  handle  of  a  Pascal  string. 

$0002  Reference  in  promptRef  is  the  resource  ID  of  a  Pascal  string 

origNameReJDesc  Defines  the  type  of  reference  in  origNameRef 

$0000  Reference  in  origNameRef  is  a  pointer  to  a  GS/OS  Class  1  Input 

string. 

$0001  Reference  in  origNameRef^  a  handle  of  a  GS/OS  Class  1  Input 

string. 

$0002  Reference  in  origNameRef  is  the  resource  ID  of  a  GS/OS  Class  1 

Input  string 

OrigNameRef       Reference  to  a  GS/OS  Class  1  Input  string.  On  input  to  SFPutFiie2, 
this  string  contains  the  default  filename  for  the  Put  operation.  On 
output,  this  string  contains  the  string  confirmed  by  the  user,  which 
may  not  be  the  same  as  the  default  value. 
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SFReScan  $1317 

Forces  the  system  to  re-build  and  re-display  the  current  list  of  files.  Your  program  may 
specify  a  new  file  type  list  or  filter  procedure. 

Make  this  call  only  while  SFPGetFiie,  SFPGetFiie2,  or  SFPMuitiGet2  are  running, 
and  only  from  within  a  dialog  hook  routine  (for  information  on  dialog  hook  routines,  see 
the  description  of  SFPOetFiie  in  Chapter  22,  "Standard  File  Operations  Tool  Set,"  in 
Volume  2  of  the  Toolbox  Reference). 

Parameters 

Stack  before  call 


Previous  conlents 


-  filterProcPtr 


typelistPlr 


Long— Pointer  to  filter  procedure;  NIL  for  no  change 

Long— Pointer  to  type  list  record;  NIL  for  no  change 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$1706 


<— SP 
badCall 


Neither  SFPOetFiie, 
SFPGetFile2, nor 
SFPMuitiGet2  is  active 


extern  pascal  void  SFReScan (filterProcPtr, 
typelistPtr) ; 


Pointer      filterProcPtr,  typelistPtr; 
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SFShowInvisible  $1217 


Controls  display  of  invisible  files.  When  the  Standard  File  Operations  Tool  Set  initializes 
itself,  invisible  files  are  not  displayed  and  are  not  passed  to  filter  procedures. 

Parameters 

Stack  before  call 

Previous  contents 


invisibleState 


Space 


Word— Space  for  result 

Word— Flag:  1  -  display  invisible  files;  0  -  no  display  (default) 


<— SP 


Stack  after  call 


Previous  contents 


oldState 


Word— Previous  setting  of  invisible  fiag 


<— SP 


Errors 


None 


C 


extern  pascal  word  SFShowInvisible (invisibleState) ; 


Word 


invisibleState; 
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Standard  File  error  codes 


This  section  lists  all  valid  Standard  File  error  codes. 


Value 


Name 


Definition 


$1701 
$1702 
$1704 

$1705 

$1706 


badPromptDesc 

badOrigNameDesc 

badReplyNameDesc 

badReplyPathDesc 

badCall 


Invalid  promptRefDesc  value 

Invalid  origNameDesc  value 

Invalid  reply  record  nameRef  Desc 
value 

Invalid  reply  record  pathRef  Desc 
value 

Neither  SFPGetFile,  SFPGetFile2, 

nor  SFPMuitiGet2  is  active 
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Chapter  49  TextEdit  Tool  Set 


This  chapter  documents  the  features  of  the  new  TextEdit  tool  set.  This  is 
a  new  tool  set,  not  previously  documented  in  the 
Apple  IIGS  Toolbox  Reference. 
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About  the  TextEdit  Tool  Set 

The  TextEdit  Tool  Set  provides  basic  text  editing  capabilities  for  any  application.  You 
can  use  TextEdit  to  support  anything  from  a  simple  text-based  dialog  box  to  a  complete 
text  editor.  While  it  has  been  loosely  based  on  the  Macintosh  tool,  TextEdit  for  the  Apple 
IIGS  includes  many  enhancements  that  expand  both  the  flexibility  and  functionality  of  the 
tool  set. 

TextEdit  for  the  Apple  IlGS  supports  a  number  of  capabilities  and  features,  including: 

■  Text  insertion,  deletion,  selection,  copying,  cutting  and  pasting,  using  standard 
keyboard  and  mouse  interfaces 

■  Editing  very  large  documents,  up  to  the  limit  of  system  memory 

■  Word  wrap,  which  avoids  splitting  words  at  the  right  text  edge 

■  Optional  support  for  intelligent  cut  and  paste,  which  eliminates  the  need  for  the  user 
to  add  or  remove  extra  spaces  after  pasting  word-based  selections 

■  Style  variations  in  the  text,  affecting  text  font,  style,  size  or  color 

■  Formatting  for  margins,  indentation,  justification,  and  tabs 

■  Left-justified  tabs,  either  evenly  spaced  or  at  specified  locations 

■  Vertical  scrolling  of  text  that  extends  beyond  the  current  display  window 
!■  Vertical  scroll  bar 

The  following  several  paragraphs  discuss  general  TextEdit  concepts,  and  present  more 
detail  on  some  TextEdit  features. 

TextEdit  provides  your  program  with  the  facilities  to  create,  display,  and  manage  one  or 
more  windows  of  editable  text.  These  windows  can  be  controls  (such  as  the  text  in  a 
dialog  box  or  the  text  window  for  an  editor)  or  independently  managed  by  your 
application.  The  Control  Manager  and  the  Window  Manager  help  your  program  manage 
TextEdit  controls;  your  program  is  solely  responsible  for  TextEdit  windows  that  are  not 
controls.  All  TextEdit  windows,  whether  or  not  they  are  controls,  are  called  records  or 
TextEdit  records. 

Since  there  can  be  many  TextEdit  records  displayed  at  the  same  time,  TextEdit  provides 
a  mechanism  for  distinguishing  between  them  that  is  based  upon  the  mechanism  used  by 
the  Control  Manager  to  move  among  controls  on  the  screen.  The  current  or  active  TextEdit 
record  is  referred  to  as  the  target  record.  That  record  receives  all  user  keystrokes  and 
mouse  commands.  The  user  can  switch  between  TextEdit  records  by  pressing  the  Tab  key 
(if  your  program  has  enabled  that  option)  or  by  clicking  in  the  appropriate  record. 
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TextEdit  maintains  a  number  of  data  staictures  for  eacii  record.  The  TERecord  is  the 
main  structure  for  a  TextEdit  record.  All  control  information  needed  for  the  record  is 
either  stored  in,  or  is  accessible  through,  the  TERecord.  In  general,  your  program  need 
not  access  or  modify  the  TERecord  unless  you  want  to  use  some  of  TextEdit's  internal 
features.  Your  program  creates  a  TextEdit  record,  and  its  TERecord,  by  formatting  a 
TEParamBiock  and  passing  that  structure  to  the  TENew  tool  call.  The  TERecord  is  an 
extension  of  the  generic  control  record  defined  by  the  Control  Manager. 

For  each  TextEdit  record,  your  program  can  instruct  TextEdit  to  use  intelligent  (or  smart) 
cut  and  paste.  The  goal  of  intelligent  cut  and  paste  is  to  eliminate  the  need  for  the  user  to 
insert  spaces  to  fix  a  paste.  With  intelligent  cut  and  paste  enabled,  TextEdit  will  make  the 
following  adjustments  to  the  current  selection: 

■  When  text  is  cut,  remove  all  leading  spaces;  if  there  are  no  leading  spaces,  remove  all 
trailing  spaces 

■  When  text  is  pasted,  if  the  current  selection  is  adjacent  to  a  nonspace  character, 
TextEdit  first  inserts  a  space,  then  the  text 

By  making  these  adjustments,  intelligent  cut  and  paste  allows  the  user  to  select  a  word  (by 
double-clicking  the  mouse,  for  instance),  and  cut  and  paste  that  selected  text  without 
adding  or  removing  any  space  characters.  Your  program  specifies  intelligent  cut  and  paste 
by  setting  a  bit  flag  in  the  textFiags  field  of  the  TEParamBiock  used  to  create  the 
record. 

TextEdit  supports  four  types  of  text  justification:  left,  center,  right,  and  full. 
Left-justified  text  lies  flush  with  the  left  margin,  with  ragged  right  edges.  Right-justified 
text  is  flush  with  the  right  margin,  with  ragged  left  edges.  Each  line  of  centered  text  is 
centered  between  the  left  and  right  margins.  Fully  justified  text  is  blocked  flush  with  both 
left  and  right  margins;  TextEdit  pads  spaces  with  extra  pbcels  to  fully  justify  the  text.  Your 
program  specifies  the  type  of  justification  for  a  TextEdit  record  as  part  of  the  initial  style 
information  in  the  TEParamBiock  for  the  record.  Your  program  can  change  the  text 
justification  for  a  record  with  the  TESetRuier  tool  call. 

TextEdit  supports  tabs  in  two  ways.  Regular  tabs  are  spaced  evenly  in  the  text,  at 
consistent  pixel  intervals.  Absolute  tabs  reside  at  specified  pixel  locations  and  can  be 
spaced  irregularly  in  the  text.  All  TextEdit  tabs  are  left  justified.  Your  program  specifies 
whether  a  TextEdit  records  supports  tabs  and,  if  so,  the  type  and  spacing  for  those  tabs 
in  the  TEParamBiock  for  the  record.  Your  program  can  change  the  tabs  for  a  record  with 
the  TESetRuier  tOOl  call. 
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TextEdit  call  summary 

The  following  table  summarizes  the  capabilities  of  the  TextEdit  Tool  Set  in  a  grouped 
listing  of  its  tool  calls.  Later  sections  of  this  chapter  discuss  TextEdit,  and  its  capabilities 
and  data  structures  in  greater  detail,  and  define  the  precise  syntax  for  the  TextEdit  tool 
calls. 


Routine  Description 


Housekeeping  routines 

TEBootinit  Initializes  TextEdit;  called  only  by  the  Tool  Locator 

TEStartup  Allocates  TextEdit  facilities  for  an  application— must 

precede  any  other  TextEdit  tool  calls 
TEShutDown  Frees  TextEdit  facilities  used  by  an  application- 

TextEdit  applications  must  issue  this  call  before 
quitting 

TEVersion  Returns  TextEdit  version  number 

TEReset  Resets  TextEdit;  called  only  when  the  system  is  reset 

TEStatus  Returns  status  information  about  TextEdit 

Record  and  text  management 

TENew  Allocates  a  new  TextEdit  record 

TEKiii  Disposes  of  an  old  TextEdit  record 

TESetText  Sets  the  text  for  an  existing  TextEdit  record 

TEGetText  Returns  the  text  from  an  existing  TextEdit  record 

TEGetTextinf  o  Retums  information  about  the  text  in  a  TextEdit  record 

Insertion  point  and  selection  range 

TEidie  Provides  processor  time  to  TextEdit  so  that  it  can  blink 

the  cursor  and  perform  background  tasks 

TEActivate  Activates  the  current  selection 

TEDeactivate  Deactivates  the  current  selection 

TECiick  Activates  a  specified  TextEdit  record,  and  selects  text 

within  that  record 

TEUpdate  Redraws  a  TextEdit  record 
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Editing 

TEKey 
TECut 

TECopy 
TEPaste 

TEClear 
TEInsert 
TEReplace 
TEGetSelection 

TESet Selection 

Text  display  and  scrolling 

TEGetSelectionStyle 

TEStyleChange 

TEGetRuler 

TESetRuler 

TEScroll 

TEOf f setToPoint 

TEPointToOf f set 

TEPaintText 

Miscellaneous  Routines 

TEGetDef Proc 
TEGetlnternalProc 
TEGetLastError 
TECompactRecord 


Inserts  a  character  into  the  target  TextEdit  record 
Cuts  the  current  selection  and  places  it  into  the  desk 
scrap 

Copies  the  current  selection  into  the  desk  scrap 
Pastes  the  contents  of  the  desk  scrap  into  the  text, 
replacing  the  current  selection 
Clears  the  current  selection 
Inserts  the  specified  text  before  the  current  selection 
Replaces  the  current  selection  with  the  specified  text 
Returns  the  starting  and  ending  character  offsets  for  the 
current  selection 

Sets  the  current  selection  to  die  specified  starting  and 
ending  character  offsets 

Returns  style  information  for  the  current  selection 
Changes  the  style  of  the  current  selection 
Returns  format  information  for  a  TextEdit  record 
Sets  format  information  for  a  TextEdit  record 
Scrolls  to  a  specified  line,  text  offset,  or  pixel  position 
Converts  a  text  offset  into  a  point  (in  local 
coordinates) 

Converts  a  point  (in  local  coordinates)  into  a  text 
offset 

Paints  TextEdit  text  into  an  off-screen  port— used  for 
printing 

Returns  a  pointer  to  the  TextEdit  custom  control 
definition  procedure 

Returns  a  pointer  to  the  TextEdit  low-level  routine 
dispatcher 

Returns  the  last  error  code  generated  for  a  TextEdit 
record 

Compresses  the  data  structures  associated  with  a 
TextEdit  record 
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How  to  use  TextEdit 

You  may  choose  between  several  techniques  for  creating  and  controlling  TextEdit  records 

■  Create  a  TextEdit  control  with  the  NewControi2  Control  Manager  tool  call,  and  allow 
TaskMaster  to  manage  the  control  for  you 

■  Create  a  TextEdit  control  with  the  NewControi2  tool  call  and  manage  the  control 
yourself 

■  Create  a  TextEdit  record  that  is  not  a  control  with  the  TENew  TextEdit  tool  call  and 
manage  it  yourself 

The  remainder  of  this  section  discusses  each  of  these  techniques  in  more  detail. 

The  simplest  technique  is  to  create  a  TextEdit  control,  using  either  the  tenbw  TextEdit 
tool  call  or  the  NewControi2  Control  Manager  call,  and  use  TaskMaster  to  manage  the 
record  (see  Chapter  25,  "Window  Manager,"  in  the  Toolbox  Reference  for  more  information 
on  TaskMaster).  TaskMaster  handles  all  TextEdit  events  and  user  interaction  for  single- 
style  records.  The  following  pseudo  code  describes  the  basic  program  logic  for  this 
technique. 

Initialize  all  the  tools  including  TextEdit. 
Create  a  new  window. 

Call  TENew.  This  allocates  a  new  TextEdit  record. 

while (  quitFlag  !=  TRUE  ) 

{ 

Call  TaskMaster.  This  handles  all  the  events;  it  inserts  all  the 

keys  that  the  user  types,  handles  all  the  mouse  activity  and 
takes  care  of  blinking  the  cursor.   It  even  calls  TECut, 
TECopy,  TEPaste,   and  TEClear  for  the  TextEdit  record. 

if(  the  user  selects  the  save  item  ) 

{ 

Call  TEGetText.  This  extracts  the  text  and  style  information 
that  the  user  has  typed. 

} 

} 

Dispose  of  the  window.  This  deallocates  the  TextEdit  record  and  all 

other  controls  in  the  window. 
Shutdown  all  the  tools  and  exit. 

Your  application  does  not  need  to  do  anything  if  the  user  presses  a  key,  clicks  the  mouse 
button,  or  selects  a  menu  item.  TaskMaster  and  the  TextEdit  control  definition  procedure 
handle  all  these  standard  events.  The  Window  Manager  will  dispose  of  the  TextEdit 
control  when  your  application  closes  its  window. 
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However,  your  program  does  give  up  some  flexibility  in  excliange  for  the  simplicity  of  this 
approach.  In  order  to  exert  somewhat  more  control  over  the  TextEdit  record,  you  may 
choose  to  create  a  TextEdit  control  and  manage  that  control  in  your  program,  rather  than 
with  TaskMaster.  Your  program  would  then  issue  the  GetNextEvent  Window  Manager 
call  to  trap  user  actions,  and  then  process  those  actions  accordingly.  The  following 
pseudo  code  shows  sample  logic  for  this  approach, 

Initialize  all  the  tools  including  TextEdit. 
Create  a  new  window. 

Call  TENew.  This  allocates  a  new  TextEdit  record, 
while (  quitFlag  !=  TRUE  ) 
{ 

Call  TEIdle.  This  blinks  the  cursor  and  performs  background 

tasks . 
Call  GetNextEvent. 
switch  theEvent . what 
{ 

case  updateEvent: 

Call  DrawControls .  This  draws  the  TextEdit  control 
(and  all  others  in  the  window) 
case  mouseDownEvent : 

Call  FindWindow.  This  determines  where  in  the 

desktop  the  mouse  was  clicked, 
if (  FindWindow  returned  inMenu  ) 
{ 

call  MenuSelect.  This  tracks  the  menu  and 

returns  which  item  the  user  clicked  in. 
switch  theMenuItem 
{ 

case  Cutltem: 

Call  TECut.  This  tells  TextEdit  to  cut 

the  current  selection  into  the  desk 
scrap, 
case  Copyltem: 

Call  TECopy.  This  tells  TextEdit  to  copy 
the  current  selection  into  the  desk 
scrap, 
case  Pasteltem: 

Call  TEPaste.  This  tells  TextEdit  to 
replace  the  current  selection  with  the 
desk  scrap. 
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case  Clearltem: 

Call  TEClear.  This  tells  TextEdit  to 
clear  the  current  selection, 
case  Saveltem: 

Call  TEGetText.  This  extracts  the  text 

and  style  information  that  the  user 
has  typed, 
case  Quitltem: 

Set  the  quitFlag  to  TRUE. 

} 

} 

else  if (  FindWindow  returned  inContent  ) 
{ 

Call  FindControl.  This  returns  which  control 

was  clicked  in. 
if (  FindControl  returned  the  TextEdit  control  ) 
{ 

call  TEClick.  This  tracks  the  mouse 

within  the  TextEdit  record;  it  does 
all  the  selecting  and  all  the 
scrolling. 

} 

} 

else 
{ 

} 

case  keyDownEvent , autoKeyEvent : 

Call  TEKey.  This  inserts  the  key  that  the  user  typed 
into  the  TextEdit  record.   It  also  performs 
editing  operations  if  the  key  is  a  "control  key" 
(like  DELETE,  CTRL-Y,   arrow  keys,   etc) . 

} 

} 

Dispose  of  the  window.  This  deallocates  the  TextEdit  record  and  all 
other  controls  in  the  window. 
Shutdown  all  the  tools  and  exit. 
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Finally,  you  may  choose  to  create  TextEdit  records  that  are  not  controls.  In  this  case,  your 
program  must  not  only  provide  complete  functional  support  for  the  record,  as  shown  in 
the  non-TaskMaster  pseudo  code,  but  also  manage  the  TextEdit  window  itself.  You  must 
use  the  tensw  call  to  create  TextEdit  records  that  are  not  controls.  These  TextEdit 
records  are  not  inserted  into  the  control  list,  so  your  program  may  not  issue  Control 
Manager  calls  to  manipulate  or  control  them.  Similariy,  your  program  may  not  use  Window 
Manager  calls  on  them.  The  following  pseudo  code  presents  sample  logic  for  this 
approach. 

Initialize  all  the  tools  including  TextEdit. 
Create  a  new  window. 

Call  TENew.  This  allocates  a  new  TextEdit  record. 

while (  quitFlag  !=  TRUE  ) 

{ 

Call  TEIdle.  This  blinks  the  cursor  and  performs  background 

tasks . 
Call  GetNextEvent . 
switch  theEvent . what 
{ 

case  updateEvent: 

Call  TEUpdate.  This  draws  the  TextEdit  record, 
case  mouseDownEvent : 

Call  FindWindow.  This  determines  where  in  the  desktop  the 
mouse  was  clicked. 

if (  FindWindow  returned  inMenu  ) 

{ 

call  MenuSelect.  This  tracks  the  menu  and  returns 

which  item  the  user  clicked  in. 
switch  theMenuItem 
{ 

case  Cutltem: 

Call  TECut.  This  tells  TextEdit  to  cut  the 

current  selection  into  the  desk  scrap, 
case  Copyltem: 

Call  TECopy.  This  tells  TextEdit  to  copy  the 
current  selection  into  the  desk  scrap, 
case  Pasteltem: 

Call  TEPaste.  This  tells  TextEdit  to  replace 

the  current  selection  with  the  desk  scrap, 
case  Clearltem: 

Call  TEClear.  This  tells  TextEdit  to  clear  the 
current  selection. 
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case  Saveltem: 

Call  TEGetText.  This  extracts  the  text  and 

style  information  that  the  user  has  typed, 
case  Quitltem: 

Set  the  quitFlag  to  TRUE. 

} 

} 

else  if (  FindWindow  returned  inContent  ) 
{ 

Figure  out  whether  the  click  occurred  in  the  TextEdit 
record. 

if (  the  click  occurred  in  the  TextEdit  record  ) 
{ 

call  TEClick.  This  tracks  the  mouse  within  the 

TextEdit  record;  it  does  all  the  selecting 
and  all  the  scrolling. 

} 

) 

else 
{ 

} 

case  keyDownEvent, autoKeyEvent : 

Call  TEKey.  This  inserts  the  key  that  the  user  typed  into 
the  TextEdit  record.  It  also  performs  editing 
operations  if  the  key  is  a  "control  key"    (like  DELETE, 
CTRL-y,  arrow  keys,  etc) . 

} 

} 

Dispose  of  the  window.  This  deallocates  the  TextEdit  record  and  all 
other  controls  in  the  window. 
Shutdown  all  the  tools  and  exit. 

With  this  technique,  your  program  has  much  more  responsibility.  First,  your  program  must 
issue  the  TEUpdate  call  for  each  record  that  must  be  redrawn,  rather  than  relying  on  the 
Control  Manager  orawcontrois  tool  call.  In  addition,  your  program  must  use  the 
TEActivate  and  TEDeactivate  tool  calls  whenever  the  user  switches  between 
TextEdit  records.  Finally,  for  each  mouse-down  event,  your  program  must  determine  in 
which  TextEdit  record  the  user  clicked— FindControi  will  not  work  with  TextEdit 
records  that  are  not  controls. 
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A  Warning  If  you  have  defined  TextEdit  records  that  are  controls  in  a  window, 
you  must  not  also  try  to  define  non-control  TextEdit  records  in  the 
same  window.  ▲ 

All  TextEdit  tool  calls  require  you  to  specify  a  handle  to  the  appropriate  TERecord,  so 
that  TextEdit  knows  which  record  to  address.  For  TextEdit  records  that  are  controls,  your 
program  may  specify  a  NULL  value  for  the  TERecord  handle.  TextEdit  will  then  access  the 
currently  active  TextEdit  control  (the  target  TextEdit  record). 

A  Warning       Never  pass  a  NULL  TERecord  handle  to  access  TextEdit  records  that 
are  not  controls,  a 

Note  that  TextEdit  routines  always  use  the  same  TERecord  layout,  whether  or  not  the 
TextEdit  record  is  a  control.  However,  if  the  TextEdit  record  is  not  a  control,  your 
program  cannot  issue  Control  Manager  tool  calls  for  it. 


Standard  TextEdit  key  sequences 

TextEdit  provides  a  keyboard  and  mouse  interface  that  supports  a  number  of  editing 
keys.  The  following  table  summarizes  the  effect  of  control  keystrokes  and  mouse  clicks: 

Key  Alias  Description 

Left  Arrow       Control-h        Moves  the  insertion  point  to  the  previous  character  in 

the  text 

Command  key  causes  movement  by  word  rather  than  by 
character 

Option  key  moves  the  insertion  point  to  the  beginning 
of  the  previous  line  in  the  text 
Shift  key  extends  the  selection  from  the  current 
insertion  point  back  by  a  character,  word  (if  the 
Command  key  is  also  held  down),  or  line  (if  the  Option 
key  is  also  held  down) 
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Right  Arrow  Control-u 


Up  Arrow  Control-k 


Down  Arrow  Control-j 


Delete  Control-d 

Clear 
Control-f 

Control-y 


Moves  the  insertion  point  to  the  next  character  in  the 
text 

Command  key  causes  movement  by  word  rather  than  by 
character 

Option  key  moves  the  insertion  point  to  the  end  of  the 
current  line  in  the  text 

Shift  key  extends  the  selection  from  the  current 

insertion  point  forward  by  a  character,  word  (if  the 

Command  key  is  also  held  down),  or  line  (if  the  Option 

key  is  also  held  down) 

Moves  the  insertion  point  up  one  line 

Command  key  moves  the  insertion  point  to  the 

beginning  of  the  current  page 

Option  key  moves  the  insertion  point  to  the  beginning 

of  the  document 

Shift  key  extends  the  selection  from  the  current 
insertion  point  up  by  a  line  or  page  (if  the  Command 
key  is  also  held  down),  or  to  the  beginning  of  the 
document  (if  the  Option  key  is  also  held  down) 
Moves  the  insertion  point  down  one  line 
Command  key  moves  the  insertion  point  to  the  current 
column  position  on  the  last  line  of  the  page 
Option  key  moves  the  insertion  point  to  the  end  of  the 
document 

Shift  key  extends  the  selection  from  the  current 
insertion  point  down  by  a  line  or  page  (if  the  Command 
key  is  also  held  down),  or  to  the  end  of  the  document 
(if  the  Option  key  is  also  held  down) 
If  there  is  no  current  selection,  removes  the  character  to 
the  left  of  the  insertion  point;  if  there  is  a  selection, 
removes  the  selected  text 

Clears  the  current  selection  (does  nothing  if  there  is  no 
selection) 

If  there  is  no  current  selection,  removes  the  character  to 
the  right  of  the  insertion  point;  if  there  is  a  selection, 
removes  the  selected  text 

Removes  all  characters  from  the  insertion  point  to  the 
end  of  the  line,  not  including  any  terminating  ASCII 
return  characters  ($0D) 
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Control-x  Cuts  the  current  selection  into  the  Clipboard  (same  as 

the  TECut  tool  call) 

Control-c  Copies  the  current  selection  into  the  Clipboard  (same  as 

the  TECopy  tool  call) 
Control-v  Pastes  the  contents  of  the  clipboard  at  the  current 

insertion  point,  or  in  place  of  any  selected  text  (same 

as  the  TEPaste  tool  call) 
Click  Moves  the  insertion  point— dragging  selects  by 

character 

Double-click  Selects  a  word— dragging  extends  the  selection  by 

words 

Triple-click  Selects  a  line— dragging  extends  the  selection  by  lines 
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Internal  structure  of  the  TextEdit  Tool  Set 

This  section  discusses  several  topics  relating  to  the  internal  structure  and  function  of  the 
TextEdit  Tool  Set.  This  information  will  not  be  relevant  to  most  application 
programmers,  but  does  provide  insight  into  how  TextEdit  operates,  and  how  to  tailor 
TextEdit  for  special  applications. 


TextEdit  controls  and  the  Control  Manager 


As  has  been  discussed,  TextEdit  records  may  or  may  not  be  controls.  Your  program 
creates  TextEdit  controls  by  issuing  the  NewControi2  Control  Manager  tool  call.  The 
Control  Manager  handles  nearly  all  the  support  calls  needed  to  maintain  the  TextEdit 
record.  However,  you  may  choose  to  use  certain  Control  Manager  tool  calls  with  the 
TextEdit  control.  The  following  tables  list  which  Control  Manager  calls  may  or  may  not  be 
used  with  TextEdit  controls.  In  this  context,  the  TextEdit  control  is  taken  to  include  the 
actual  TextEdit  record  and  its  associated  scroll  bars  and  size  box. 

The  following  Control  Manager  calls  may  be  used  with  TextEdit  controls: 


CaU 


Description 


DisposeControl 


KillControls 


HideControl 


EraseControl 

ShowControl 

DrawControls 
DrawOneCtl 


Disposes  of  the  TextEdit  control— analogous  to 

TEKiii  TextEdit  tool  call 

Disposes  of  all  controls,  including  the  TextEdit 

controls— analogous  to  tekiii  tool  calls  for  each 

control 

Hides  the  TextEdit  control— note  that  this  call  does 
not  affect  the  status  of  the  control  with  respect  to  user 
keystokes;  if  you  hide  the  target  control,  it  is  still  the 
target  control,  although  no  user  keystrokes  will  be 
displayed 

Erases  the  TextEdit  control- similar  to  Hi  decontrol, 
except  that  EraseControl  does  not  invalidate  the 
boundary  rectangle  for  the  control 

Reshows  the  TextEdit  control,  reversing  the  effect  of 
HideControl  Or  EraseControl 
Draws  all  controls  in  the  window 
Draws  the  specified  TextEdit  control 
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MoveControl 


DragControl 


HilightControl 


FindControl 


TestControl 


GetCtlRefCon 


TrackControl 


SetCtlRefCon 


Activates  or  deactivates  the  TextEdit  control— note 
that  only  hiliteStale  \z\ues  of  0  and  255  are  valid 
Returns  point  location  control  identification 
information— returns  partCode  of  130  if  point  is  in  text, 
131  if  point  is  in  vertical  saoll  bar,  and  132  if  point  is  in 
size  box 

Returns  the  same  point  location  information  as 

FindControl,  without  any  control  identification 

Selects  text— actionProcPtr  must  be  set  to  a  negative 

value  (forces  the  Control  Manager  to  use  TextEdit's 

built-in  action  procedure) 

Moves  the  TextEdit  control 

Allows  the  user  to  reposition  the  TextEdit  control 

Sets  the  refCon  field 

Returns  the  contents  of  the  refCon  field 


Your  program  must  not  issue  the  following  Control  Manager  tool  calls  with  a  TextEdit 
control: 

GetCtlTitle 

GetCtlValue 

GetCtlAction 

GetCtlParams 

SetCtlTitle 

SetCtlValue 

SetCtlAction 

SetCtlParams 


TextEdit  fUter  procedures  and  hook  routines 

TextEdit  provides  you  with  several  mechanisms  to  tailor  the  operation  of  the  tool  set  to 
the  particular  needs  of  your  application.  Filter  procedures  give  you  a  chance  to  affect  the 
behavior  of  the  tool  set  by  modifying  screen  display  activity  or  user  keystrokes.  Hook 
routines  allow  you  to  replace  standard  TextEdit  code  for  such  functions  as  word  wrap  or 
word  break.  The  following  several  sections  discuss  each  of  the  various  filter  procedures 
and  hook  routines  in  more  detail. 
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Generic  filter  procedure 

TextEdit  provides  a  facility  whereby  your  application  can  supply  special  logic  to  replace 
some  of  the  standard  TextEdit  routines.  The  program  code  that  uses  this  facOity  is  called 
a  generic  filter  procedure.  The  generic  filter  procedure  is,  in  turn,  made  up  of  several 
routines  that  address  particular  TextEdit  processing  requirements.  At  present,  there  are 
diree  functions  that  generic  filter  routines  can  provide; 

■  Erasing  rectangles  in  the  display  port 

■  Erasing  rectangles  in  the  off-screen  TextEdit  buffer 

■  Updating  the  TextEdit  record  screen  display 

The  TERecord  f  iiterProc  field  contains  a  pointer  to  the  generic  filter  procedure.  If 
this  field  has  a  non-NULL  value,  TextEdit  will  call  the  filter  procedure  to  perform  the 
activities  just  mentioned.  You  set  this  pointer  by  specifying  the  appropriate  value  in  the 
filterProcPtr  field  of  the  TEParamBlock  passed  tO  TENew  (orNewControl2) 
when  you  create  the  TextEdit  record.  TextEdit  then  loads  thefiiterProc  field  of  the 
TERecord  from  this  value. 

The  routines  in  the  filter  procedure  must  adhere  to  the  following  rules: 

■  The  routine  must  preserve  the  direct  page  and  data  bank  registers,  and  must  return  in 
full  native  mode. 

■  All  entry  and  exit  parameter  and  status  fields  must  be  passed  through  the  appropriate 
TERecord. 

■  Filter  routines  must  not  issue  TextEdit  tool  calls,  move  memory,  or  cause  memory  to 
be  moved. 

■  Any  application-specific  routine  messages  must  have  message  numbers  greater  than 
$8000— TextEdit  reserves  all  message  number  values  in  the  range  from  $0000  through 
$7FFF. 

TextEdit  invokes  the  generic  filter  procedure  in  full  native  mode  by  executing  a  jsl.  On 
entry  to  the  filter  procedure,  the  stack  is  formatted  as  follows; 

Previous  contents 


teHandle 


message 


Space 


RTL 


Word— Space  for  result 
Long— Handle  to  the  appropriate  TERecord 
Word— Message  number  indicating  action  to  take 
Three  bytes— Retum  address 


<— SP 
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On  exit,  the  filter  procedure  must  format  the  stack  as  follows: 


Previous  contents 


Result 


Word— Result  code 
<— SP 

result  Indicates  whether  the  filter  procedure  handled  the  message.  If  the 

field  is  set  to  $0000,  then  TextEdit  will  perform  its  standard 
processing.  If  the  field  is  nonzero,  then  the  filter  procedure  handled 
the  message,  and  TextEdit  does  not  perform  its  standard  processing. 

The  following  sections  discuss  each  defined  filter  procedure  message,  defining  the 
actions  the  filter  procedure  is  to  take  and  the  affected  TERecord  fields. 


doEraseRect  ($0001) 

The  filter  procedure  is  to  erase  a  rectangle  in  the  display  port  for  the  current  TextEdit 
record.  TextEdit  has  already  set  up  the  port  for  the  filter  routine. 

TextEdit  provides  this  routine  to  support  applications  that  maintain  overlaying  objects 
on  the  display.  Under  such  circumstances,  the  application  must  decide  what  object  to 
make  visible  after  the  user  has  caused  a  currently  visible  object  to  be  deleted. 

Input: 

TKR.cord  field   Contents  

theFiiterRect  Specifies  the  rectangle  to  erase,  expressed  in  local 

coordinates  for  the  port 

Output: 

None 
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doEraseBuffer  ($0002) 

The  filter  procedure  is  to  move  a  rectangle  from  TextEdit's  offscreen  buffer  to  the  display 
port.  The  TERecord  contains  information  defining  the  source  and  destination  data 
locations.  TextEdit  has  already  set  up  the  port  for  the  filter  routine. 

This  routine  is  used  in  much  the  same  way  as  doEraseRect,  except  that  it  operates  off- 
screen, rather  than  on-screen. 

Input: 

TKRacoxd  field  Contents 


theFiiterRect  Specifies  the  rectangle  to  erase,  expressed  in  local 

coordinates  for  the  offscreen  buffer  port 
theBuf  f  erVPos  Vertical  position  corresponding  to  the  top  of  the 

destination  buffer  in  the  display  port,  expressed  in  local 

coordinates  for  the  port 
theBuf  ferHPos  Horizontal  position  corresponding  to  the  left  edge  of 

the  destination  buffer  in  the  display  port,  expressed  in 

local  coordinates  for  the  port 

Output: 

None 
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doRectChanged  ($0003) 

The  filter  procedure  is  to  handle  a  change  to  the  display  window  for  the  TextEdit  record. 
Note  that  TextEdit  has  not  set  up  the  port;  the  filter  procedure  must  obtain  the  port  from 
the  inPort  field  of  the  TERecord,  and  set  up  the  display  port. 

With  this  routine  your  application  can  maintain  an  off-screen  copy  of  its  TextEdit 
display.  Whenever  TextEdit  updates  the  screen,  it  issues  this  message  to  the  generic  filter 
procedure,  which  can  update  the  saved  screen  copy. 

Input: 

TER.cord  field  Contents 


theFiiterRect  Specifies  the  rectangle  that  changed,  expressed  in  local 

coordinates  for  the  port 

Output: 

None 
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Keystroke  filter  procedure 

TextEdit  also  provides  a  mechanism  for  applications  to  supply  custom  keystroke 
processing  for  a  TextEdit  record.  TextEdit's  internal  keystroke  routine  supports  the 
standard  keyboard  interface  described  in  "Standard  TextEdit  key  sequences"  in  this 
chapter.  Custom  keystroke  processing  may  support  different  keyboard  mappings  or 
macro  facilities. 

The  keyFiiter  field  of  a  TERecord  can  contain  a  pointer  to  a  keystroke  filter 
procedure.  If  keyFiiter  is  NULL,  TextEdit  uses  its  standard  keystroke  routine.  If 
keyFiiter  is  non-NULL,  TextEdit  calls  the  routine  pointed  to  by  keyFiiter  to 
process  all  user  keyboard  input. 

Keystroke  filter  procedures  must  follow  many  of  the  same  rules  established  for  generic 
filter  procedures: 

■  The  procedure  must  preserve  the  direct-page  and  data  bank  registers,  and  must  return 
in  full  native  mode. 

■  Keystroke  filter  procedures  must  not  issue  TextEdit  tool  calls. 

TextEdit  invokes  the  keystroke  filter  procedure  in  full  native  mode  by  executing  a  jsl. 
Fields  in  the  KeyRecord  TERecord  sub-structure  contain  information  defining  the  data 
to  be  processed: 

Kay R*  cord  Qeld  Contents 

thechar  This  field  contains  the  keystroke  to  process. 

theModifiers  This  field  contains  flags  indicating  the 

state  of  the  modifier  keys  at  the  time  the  key  was 
pressed;  the  keystroke  is  contained  in  theChar  and 
thelnputHandle. 

thelnputHandle  Handle  tO  a  COpy  of  theChar. 

TextEdit  loads  additional  control  information  onto  the  stack.  On  entry  to  the  filter 
procedure,  the  stack  is  formatted  as  follows: 

Previous  contents 

teHandle     -  Long— Handle  to  the  appropriate  TERecord 
type  Word— Type  of  data  to  be  processed 
RTL        -  Three  bytes— Return  address 

<— SP 
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type 


Indicates  the  type  of  data  to  be  processed: 


$0002 


$0001 


KeyRecord  theChar  field  contains  the  single  character  to  be 

processed 

Reserved 


The  keystroke  filter  procedure  is  now  free  to  perform  whatever  processing  is  appropriate. 
For  example,  it  may  change  the  input  keystroke  value  in  order  to  support  a  different 
mapping  of  the  standard  TextEdit  keyboard  functions.  Or,  the  routine  may  expand  the 
keystroke  in  theChar  into  a  block  of  text  to  be  inserted  at  the  current  location.  The 
routine  then  formats  the  appropriate  return  data  into  the  KeyRecord  fields  and  returns 
control  to  TextEdit  by  issuing  an  rtl  instruction  (after  removing  all  input  parameters 
from  the  stack). 

On  exit,  the  filter  procedure  must  format  the  stack  as  follows; 
Previous  contents 


<— SP 
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The  filter  procedure  indicates  what  action  TextEdit  is  to  take  with  the  theOpCode  field 
in  the  KeyRecord.  This  code  in  turn  governs  how  TextEdit  interprets  the  remainder  of 
the  returned  KeyRecord.  Valid  theOpCode  values  are: 


thsOpCod* 


Value 


TextEdit  action 


opNontial 


opNothing 
opReplaceText 


$0000 


$0002 
$0004 


opMoveCursor 

opExtendCursor 

opCut 

opCopy 
opPaste 

opClear 


$0006 

$0008 

$000A 

$000C 
$000E 

$0010 


TextEdit  performs  its  standard  processing  on  the 

character  stored  in  the  location  referred  to  by 

thelnputHandle 

TextEdit  ignores  the  keystroke 

TextEdit  inserts  the  text  referred  to  by 

thelnputHandle  in  place  of  the  current  selection  in 

the  record;  if  there  is  no  current  selection,  TextEdit 

inserts  the  text  at  the  current  insertion  point— if 

thelnputHandle  has  0  size,  TextEdit  deletes  the 

current  selection  and  inserts  nothing 

TextEdit  moves  the  cursor  to  the  location  specified  by 

cursorOf f set 

TextEdit  extends  the  current  selection  from  its  anchor 
point  to  the  location  specified  by  cursorOf  f  set 
TextEdit  moves  the  current  selection  and  to  the  desk 
scrap 

TextEdit  copies  the  current  selection  to  the  desk  scrap 
TextEdit  inserts  the  contents  of  the  desk  scrap  in  place 
of  the  current  selection 
TextEdit  clears  the  current  selection 
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The  following  table  summarizes  the  contents  of  the  KeyRecord  on  return  from  the 
keystroke  filter  procedure: 


KayKacord  field 


Contents 


theChar 
theModif iers 
thelnputHandle 


cursorOf f set 


theOpCode 


Unchanged 

Contains  changed  modifiers  (only  for  opNormai) 
Handle  to  replacement  text  (only  for  opNormai  and 
opRepiaceText),  length  of  text  indicated  by  size  of 
handle; 

If  TextEdit  is  to  move  the  cursor  (theOpCode  is  set  to 
either  opMoveCursor  or  opExtendCursor),  this 
field  contains  the  new  cursor  location;  otherwise, 
TextEdit  ignores  this  field. 
Specifies  next  action  for  TextEdit 
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Word  wrap  hook 


Your  program  may  supply  its  own  routine  to  handle  word  wrap.  This  word  wrap  hook 
routine  determines  whether  a  character  string  typed  by  the  user  fits  on  the  current  line 
(does  not  wrap)  or  needs  to  begin  a  new  line  (does  wrap).  TextEdit  then  displays  the 
character  string  on  the  appropriate  line. 

TextEdit  determines  whether  to  call  a  custom  word  wrap  routine  by  examining  the 
wordwrapHook  TERecord  field  for  the  TextEdit  record.  If  that  field  is  NULL,  TextEdit 
uses  its  standard  word  wrap  routine.  If  that  field  is  non-NULL,  TextEdit  calls  the  routine 
pointed  to  by  that  field  whenever  a  word  wrap  decision  is  required.  Your  program  sets  this 
pointer  by  directly  modifying  the  wordwrapHook  field  of  the  appropriate  TERecord. 

Word  wrap  hook  routines  must  follow  many  of  the  rules  established  for  generic  filter 
procedures: 

■  The  routine  must  preserve  the  direct-page  and  data  bank  registers,  and  must  return  in 
full  native  mode. 

■  Word  wrap  routines  must  not  issue  TextEdit  tool  calls,  move  memory,  or  cause 
memory  to  be  moved. 

TextEdit  invokes  the  word  wrap  hook  procedure  in  full  native  mode  by  executing  a  jsl. 
Entry  parameters  refer  the  procedure  to  the  correct  TERecord  and  character.  On  exit,  the 
word  wrap  procedure  returns  a  flag  indicating  whether  the  character  caused  a  word  wrap. 

On  entry  to  the  procedure,  the  stack  is  formatted  as  follows: 


Previous  contend 


Space 


teHandle 


theChar 


RTL 


Word— Space  for  result 

Long— Handle  to  the  appropriate  TERecord 

Word— Character  to  check 

Three  bytes— Return  address 

<— SP 


On  exit,  the  filter  procedure  must  format  the  stack  as  follows: 


Previous  contents 


wrapFlag 


Word— Flag  indicating  wrap  status 
<— SP 
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lorapFlag  Indicates  wrap  status  for  the  current  character: 

$0000  Not  a  word  wrap  (TextEdit  will  leave  the  word  on  the  current 

line) 

$FFFF  Word  wrap  (TextEdit  will  move  the  word  to  the  next  line) 
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Word  break  hook 

Your  program  may  supply  its  own  routine  to  determine  word  breaks  when  the  user  is 
selecting  text  by  words  (user  has  double-clicked  on  a  word  and  is  now  extending  that 
selection).  This  word  break  hook  routine  decides  whether  the  cursor  resides  at  a  break 
between  words,  If  so,  TextEdit  includes  the  next  word  in  the  current  selection. 

TextEdit  determines  whether  to  call  a  custom  word  wrap  routine  by  examining  the 
wordBreakHook  TERecord  field  for  the  TextEdit  record.  If  that  field  is  NULL, 
TextEdit  uses  its  standard  word  break  routine.  If  that  field  is  non-NULL,  TextEdit  calls  the 
routine  pointed  to  by  that  field  whenever  a  word  break  decision  is  required.  Your  program 
sets  this  pointer  by  direcdy  modifying  the  wordBreakHook  field  of  the  appropriate 
TERecord. 

Word  break  hook  routines  must  follow  many  of  the  rules  established  for  generic  filter 
procedures: 

■  The  routine  must  preserve  the  direct-page  and  data  bank  registers,  and  must  return  in 
full  native  mode. 

■  Word  break  routines  must  not  issue  TextEdit  tool  calls,  move  memory,  or  cause 
memory  to  be  moved. 

TextEdit  invokes  the  word  break  hook  procedure  in  full  native  mode  by  executing  a  jsl. 
Entry  parameters  refer  the  procedure  to  the  correct  TERecord  and  character.  On  exit,  the 
word  break  procedure  returns  a  flag  indicating  whether  the  character  constitues  a  word 
break. 

On  entry  to  the  procedure,  the  stack  is  formatted  as  follows: 


Piwious  contents 


Space 


teHandle 


theChar 


RTL 


Word— Space  for  result 

Long— Handle  to  the  appropriate  TERecord 

Word— Character  to  check 

Three  bytes— Return  address 

<— SP 


On  exit,  the  filter  procedure  must  format  the  stack  as  follows: 


Previous  contents 


breakFlag 


Word— Flag  indicating  break  status 
<— SP 
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breakFlag  Indicates  break  status  for  the  current  character: 

$0000  Not  a  word  break  (TextEdit  will  not  extend  the  selection) 

$FFFF  Word  break  (TextEdit  will  extend  the  selection  to  include  next 

word) 
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Custom  scroll  bars 

Your  program  may  specify  a  custom  scroll  bar  for  vertical  scrolling  of  a  TextEdit  record. 
Use  the  vertear  field  of  the  TEParamBiock  record  to  specify  a  handle  to  the  control 
record  for  the  custom  scroll  bar.  This  scroll  bar  need  not  reside  in  the  TextEdit  record 
display  port,  but  it  must  follow  certain  rules  with  respect  to  the  format  and  content  of  its 
control  record  (see  Chapter  28,  "Control  Manager  Update,"  in  this  book  and 
Chapter  4,  "Control  Manager,"  in  the  Toolbox  Reference  for  details  on  scroll  bar  controls  and 
control  records); 

■  Fields  corresponding  to  the  datasize,  viewsize,  and  ctivaiue  fields  of  a 
standard  scroll  bar  control  record  must  be  located  at  the  same  relative  locations  within 
the  custom  control  record. 

■  TextEdit  stores  a  handle  to  the  appropriate  TERecord  in  the  ctiRef  con  field  of  the 
scroll  bar  control  record.  Do  not  change  the  contents  of  this  field.  If  you  need  to  store 
additional  information  in  the  scroll  bar  control  record,  extend  the  record  handle  and 
format  that  data  after  the  standard  control  record  fields  (be  sure  to  extract  the  size  of 
the  returned  handle,  rather  than  relying  on  current  record  definitions  for  the  size  of  the 
control  record). 

■  TextEdit  stores  a  pointer  to  its  internal  text  scroll  routine  in  the  ctiAction  field 
ofthe  scroll  bar  control  record  when  the  TextEdit  record  is  created  (during  execution 
of  the  TENew  or  NewControi2  tool  Call).  Your  program  may  change  the  contents  of 
this  field,  but  should  save  the  pointer,  so  that  you  can  call  the  TextEdit  text  scroll 
routine  when  appropriate.  For  information  on  the  interface  to  action  routines, 
see"Track  Control"  in  Chapter  4,  "Control  Manager,"  of  the  Toolbox  Reference. 

Refer  to  Chapter  4,  "Control  Manager,"  for  background  information  on  writing  and 
invoking  control  definition  procedures. 
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TextEdit  data  structures 

This  section  defines  and  discusses  the  various  data  structures  used  by  the  TextEdit  Tool 
Set.  The  TextEdit  data  structures  are  divided  into  high-level  data  structures  and  low-level 
data  structures.  High-level  TextEdit  data  structures  are  of  interest  to  all  application 
programmers  who  use  TextEdit  facilities.  Low-level  TextEdit  data  structures,  on  the  other 
hand,  are  not  relevant  to  most  application  programmers.  However,  if  your  program  uses 
the  low-level  features  of  TextEdit,  or  must  for  some  other  reason  direcdy  access  TextEdit 
data  structures,  you  should  familiarize  yourself  with  the  information  in  that  section. 

In  most  cases,  it  is  not  necessary  for  your  program  to  direcdy  modify  fields  in  these 
structures.  However,  if  your  program  manipulates  TextEdit  structures,  note  that  many  of 
these  data  structures  refer  to  or  depend  upon  one  another.  Whenever  your  application 
changes  one  of  these  structures,  you  must  be  careful  to  update  other  affected  or 
dependent  structures. 
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High-level  TextEdit  structures 

TextEdit  uses  a  number  of  staictures  to  store  information  about  a  TextEdit  record  and  to 
pass  that  information  to  TextEdit  tool  calls.  The  following  sections  define  the  format  and 
content  of  each  of  these  structures,  and  describe  how  your  program  would  use  them. 

TEColorTable 

Defines  color  attributes  for  a  TextEdit  record. 

The  TEParamBiock  and  TERecord  contain  references  to  color  tables  stored  in 
TEColorTable  format. 

Note  that  all  bits  in  TextEdit  color  words  (such  as  contentcoior)  are  significant. 
TextEdit  generates  QuickDraw  II  color  patterns  by  replicating  a  color  word  the 
appropriate  number  of  times  for  the  current  resolution  (8  times  for  640  mode,  16  times  for 
320  mode).  See  Chapter  16,  "QuickDraw  II,"  for  more  information  on  QuickDraw  II 
patterns  and  dithered  colors. 
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u   Figure  49-1     TECoiorTabie  layout 


$00 

—       contentColor  — 

Word 

$02 

—       outllneColor  — 

Word 

$04 

—    hlllghtForeColor  — 

Word 

$06 

—    hilightBackColor  — 

Word 

$08 

— vertColorDescriptor— 

Word 

$0A 

—       vertColorRef  — 

Long 

$0E 

— horzColorDescriptor— 

Word 

$10 

—       horzColorRef  — 

Long 

$14 

— growColorDescrlptor— 

Word 

$16 

—       growColorRef  — 

Long 

contentColor   Defines  the  color  for  the  entire  boundary  rectangle  (in  essence, 
defining  the  background  color  for  the  text  window) 

outiinecoior   Defines  the  color  for  box  that  surrounds  the  text  in  the  display 
window. 

hilightForeColor 

Defines  the  foreground  color  for  highlighted  text. 

hilightBackColor 

Defines  the  background  color  for  highlighted  text. 
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vertColorDescriptor 

Defines  the  type  of  reference  stored  in  vertcoiorRef : 

ref  isPointer  $0000    The  vertcoiorRef  field  contains  a  pointer  to  the 

color  table  for  the  vertical  scroll  bar 

refisHandie    $0004    The  vertcoiorRef  field  contains  a  handle  to  the  color 

table  for  the  vertical  scroll  bar 

reflsResource      $0008    The  ve  r t  Co  i  o  r Re  f  field  contains  the  resource  ID  for 

the  color  table  for  the  vertical  scroll  bar 

vertcoiorRef 

Reference  to  the  color  table  for  the  vertical  scroll  bar.  The 
vertColorDescriptor  field  indicates  the  type  of  reference  stored 
here.  This  field  must  refer  to  a  scroll  bar  color  table,  as  defined  in 
Chapter  4,  "Control  Manager,"  of  the  Toolbox  Reference. 

horzColorDescriptor 

Defines  the  type  of  reference  stored  in  horzCoiorRef : 

reflsPointer        $0000    The  horzCoiorRef  field  contains  a  pointer  to  the 

color  table  for  the  horizontal  scroll  bar 

reflsHandle        $0004    The  horzCoiorRef  field  contains  a  handle  to  the  color 

table  for  the  horizontal  scroll  bar 

reflsResource      $0008    The  horzCoiorRef  field  contains  the  resource  ID  for 

the  color  table  for  the  horizontal  scroll  bar 

horzCoiorRef   Reference  to  the  color  table  for  the  horizontal  scroll  bar. 

horzColorDescriptor  indicates  the  type  of  reference  stored  here.  This 
field  must  refer  to  a  Scroll  bar  color  table,  as  defined  in 
Chapter  4,  "Control  Manager,"  of  the  Toolbox  Reference. 

growColorDescriptor 

Defines  the  type  of  reference  stored  in  growCoiorRef  .- 

reflsPointer       $0000    The  growCoiorRef  field  contains  a  pointer  to  the 

color  table  for  the  size  box 

reflsHandle        $0004    The  growCoiorRef  field  contains  a  handle  to  the  color 

table  for  the  size  box 

reflsResource      $0008    The  growCoiorRef  field  contains  the  resource  ID  for 

the  color  table  for  the  size  box 
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growCoiorRef    Reference  to  the  color  table  for  the  size  box.  The 

growCoiorDescriptor  field  indicates  the  type  of  reference  stored 
here.  This  field  must  refer  to  a  size  box  color  table,  as  defined  in 
Chapter  4,  "Control  Manager,"  of  the  Toolbox  Reference. 
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TEFormat 

This  strucaire  stores  text  formatting  control  information.  From  this  structure,  you  can 
access  the  rulers  and  styles  defined  for  the  text. 

Many  TextEdit  tool  calls  use  this  structure  to  accept  or  return  format  data  for  a  text 
record. 

■   Figure  49-2     TEFormat  layout 


$00 

version 

Word 

$02 

rulerListLength 

Long 

$06 

theRulerList 

Array  of  TERuler  structures 

$xx 

StyleLlstLength 

Long 

$xx 

theStyleLlst 

Array  of  TEStyle  structures 

$xx 

nuitiberOfStyles 

Long 

$xx 

■  thestyles 

i 

:  Array  of  Styleltem  struQures 

i 

version  Version  number  corresponding  to  the  layout  of  this  TEFormat 

structure.  This  version  of  the  structure  carries  a  version  number  of 
$0000. 

rulerListLength 

The  length  of  theRulerList  in  bytes. 

theRulerList    Ruler  data  for  the  text  record.  The  TERuler  structure  is  embedded 
within  the  TEFormat  structure  at  this  location. 
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styleList Length 

The  length  of  thestyieList  in  bytes. 

thestyieList    List  of  all  unique  styles  for  the  text  record.  The  XEStyie  structures 
are  embedded  within  the  TEFormat  structure  at  this  location.  Each 
TEStyie  structure  must  define  a  unique  style— there  must  be  no 
duplicate  style  entries.  In  order  to  apply  the  same  style  to  multiple 
blocks  of  text,  you  should  create  additional  styieitems  for  each 
block  of  text,  and  make  each  item  refer  to  the  same  style  in  this  array 

numberOf styles 

The  number  of  styieitems  contained  in  thestyies. 

thestyies        Array  of  styieitems  specifying  which  actual  styles  (stored  in 
thestyieList)  apply  to  which  text  within  the  TextEdit  record. 
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TEParamBlock 

This  structure  contains  the  parameters  necessary  to  create  a  new  TextEdit  record.  In  it 
your  program  defines  many  of  the  attributes  of  the  record.  The  format  of  this  structure 
directly  corresponds  to  the  format  of  the  TextEdit  control  template  accepted  by  the 
NewControi2  Control  Manager  call  when  creating  TextEdit  controls. 

The  TENew  tool  call  requires  that  its  input  parameters  be  specified  in  a  TEParamBiock 
structure.  Many  of  the  fields  of  the  TEParamBiock  direcdy  establish  the  values  for 
TERecord  fields. 

In  the  following  figure,  optional  fields  are  marked  with  an  asterisk  (*). 
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Figure  49-3     TEParamBiock  layout 


pCount 

Word— Parameter  count  for  template:  7  to  23 

$02 

- 

ID 

Long— Application-assigned  control  ID 

$06 

rect 

Rectangle— Boundary  reaangle  for  control 

$0E 

procRef 

Long— editTextControl=$85000000 

$12 

flag 

Word— Highlight  and  control  flags  for  control 

$14 

moreFlags 

Word— Additional  control  flags 

re f Con 

- 

Long— Application-defined  value 

$1A 

textFlags 

Long— Specific  TextEdit  control  flags  (see  below) 

$1E 

*lndentRect 

Rectangle— Defines  text  indentation  from  control  rea  (optional) 

$26 

•vert Bar 

Long— Handle  to  vertical  scroll  bar  for  control  (optional) 

$2A 

*vert Amount 

Word— Vertical  saoll  amount,  in  pixels  (optional) 

$2C 

•horzBar 

Long— Reserved;  must  be  set  to  NILL  (optional) 

$30 

*horzAmount 

Word— Reserved;  must  be  set  to  0  (optional) 

continued 
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continued 

$32 

*styleRef 

- 

Long— Reference  to  initial  style  information  for  text  (optional) 

$36 

* text Descriptor 

WnrH  Df*finp<;  fnrmar  nf  initial  tPxT  and  t^^ytRef  rnntinnal"^ 

$38 

* text Re f 

— 

Long— Reference  to  initial  text  for  edit  window  (optional) 

$3C 

*text Length 

Long— Length  of  initial  text  (optional) 

$40 

*maxChars 

— 

Long— Maximum  number  of  charaaers  allowed  (optional) 

$44 

*iTiaxLlnes 

Long— Reserved;  must  be  set  to  0  (optional) 

$48 

*maxCharsPerLlnes 

Word— Reserved;  must  be  set  to  0  (optional) 

$4A 

*maxHeight 

Word— Reserved;  must  be  set  to  0  (optional) 

$4C 

*colorRef 

Long— Reference  to  TextEdit  color  table  (optional) 

$50 

♦drawMode 

Word— QuickDraw  II  text  mode  for  edit  window  (optional) 

$52 

*filterProcPtr 

Long— Pointer  to  filter  routine  for  this  control  (optional) 

pcount  Number  of  parameter  fields  to  follow.  Valid  values  lie  in  the  range  from 

7  to  23.  The  value  of  this  field  does  not  include  pCount  itself. 

ID  Unique  ID  for  TextEdit  controls.  Your  application  sets  this  field,  and 

can  use  it  to  uniquely  identify  a  particular  TextEdit  record. 
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boundsRect       Boundary  rectangle  for  the  TextEdit  record.  This  rectangle  contains 


the  entire  record,  including  its  scroll  bars  and  outline.  If  you  set  the 
bottom  right  corner  of  this  rectangle  to  (0,0),  TextEdit  uses  the 
bottom  right  corner  of  the  window  that  contains  the  record  as  a 
default.  Note  that  this  rectangle  must  be  large  enough  to  completely 
display  a  single  character  in  the  largest  allowed  font. 


procRef 


flag 


Specifies  the  type  of  control.  Must  be  set  to  $85000000. 

Control  flags  for  the  TextEdit  record.  Defined  bits  for  flag  are  as 
follows: 


Reserved 

ctllnvis 

Reserved 


bits  8-15    Must  be  set  to  0 
bit  7         l=invisible,  0=visible 
bits  0-6     Must  be  set  to  0 
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moreFiags        More  control  flags  for  TextEdit  record.  Defined  bits  for  moreFiags 
are  as  follows: 

f  ctiTarget  bit  15       Indicates  whether  this  TextEdit  record  is  the  current 

target  of  user  actions.  Must  be  set  to  0  when  creating 
a  TextEdit  record. 

Must  be  set  to  1.  TextEdit  will  set  this  bit  to  0  if  the 
fDisableSelection  flag  in  textFlags  is  set 

tol. 

Must  be  set  to  1.  TextEdit  will  set  this  bit  to  0  if  the 
fDisableSelection  flag  in  textFlags  is  set 

tol. 

Must  be  set  to  1 

If  set  to  1,  TextEdit  will  create  a  size  box  in  the 
bottom  right  corner  of  the  window.  Whenever  the 
window  is  resized,  the  edit  text  will  be  resized  and 
redrawn. 
Must  be  set  to  1 
Must  be  set  to  0 

Defines  type  of  reference  in  coiorRef : 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 
10  -  color  table  reference  is  resource  ID 
11 -invalid  value 

bits  0-1     Defines  type  of  style  reference  in  styieRef : 

00  -  style  reference  is  pointer 

01  -  style  reference  is  handle 

10  -  style  reference  is  resource  ID 

11  -  invalid  value 


fCtlCanBeTarget    bit  14 


fCtlWantsEvents     bit  13 


fCtlProcNotPtr  bit  12 
fTellAboutSize      bit  11 


fCtllsMultiPart    bit  10 
Reserved  bits  4-9 

Color  Table  Reference  bits  2-3 


Style  Reference 


A  Important     Do  not  set  f  TeiiAboutsize  to  1  unless  the  window  also  has  a 
vertical  scroll  bar.  a 
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textFlags 


fNotControl 


f SingleFormat 
f SingleStyle 


fNoWordWrap 


fNoScroll 


fReadOnly 


Specific  TextEdit  control  flags.  Valid  values  for  textFlags  are  as 
follows; 


bit  31 


bit  30 
bit  29 


bit  28 


bit  27 


bit  26 


f SmartCutPaste 


fTabSwitch 


fDrawBounds 


bit  25 


bit  24 


bit  23 


fColorHilight 
f GrowRuler 


bit  22 
bit  21 


Indicates  whether  the  the  TextEdit  record  to  be 

created  is  for  a  control: 

1  -  TextEdit  record  is  not  a  control 

0  -  TextEdit  record  is  a  control 
Must  be  set  to  1 

Allows  you  to  restrict  the  style  options  available  to 
the  user; 

1  -  Allow  only  one  style  in  the  text 

0  -  Do  not  restrict  the  number  of  styles  in  the  text 
Allows  you  to  control  TextEdit  word  wrap  behavior; 

1  -  Do  not  word  wrap  the  text;  only  break  lines  on  CR 
($0D)  characters 

0  -  Perform  word  wrap  to  fit  the  ruler 
Controls  user  access  to  scrolling: 

1  -  Do  not  allow  either  manual  or  auto-scrolling 

0  -  Scrolling  permitted 

Restricts  the  text  in  the  window  to  read-only 
operations  (copying  from  the  window  will  still  be 
allowed): 

1  -  No  editing  allowed 

0  -  Editing  permitted 

Controls  TextEdit  support  for  smart  cut  and  paste: 

1  -  Use  smart  cut  and  paste 

0  -  Do  not  use  smart  cut  and  paste 
Defines  behavior  of  the  Tab  key: 

1  -  Tab  to  next  control  in  the  window 

0  -  Tab  inserted  in  TextEdit  document 

Tells  TextEdit  whether  to  draw  a  box  around  the  edit 
window,  just  inside  boundsRect— the  pen  for  this 
box  is  two  pixels  wide  and  one  pixel  high 

1  -  Draw  rectangle 

0  -  Do  not  draw  rectangle 
Must  be  set  to  0. 

Tells  TextEdit  whether  to  resize  the  ruler  in  response 
to  the  user  resizing  the  edit  window.  If  set  to  1, 
TextEdit  will  automatically  adjust  the  right  margin 
value  for  the  ruler: 

1  -  Resize  the  ruler 

0  -  Do  not  resize  the  ruler 
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fDrawInactiveSelection 
bit  19 


fDi sable Select ion 

bit  20       Controls  whether  user  can  select  text: 
1  -  User  cannot  select  text 

0  -  User  can  select  text 

Controls  how  inactive  selected  text  is  displayed: 

1  -  TextEdit  draws  a  box  around  inactive  selections 
0  -  TextEdit  does  nothing  special  when  displaying 
inactive  selections 

Reserved  bits  0-18    Must  be  set  to  0 

indentRect       Each  coordinate  of  this  rectangle  specifies  the  amount  of  white  space 
to  leave  between  the  boundary  rectangle  for  the  control  and  the  text 
itself,  in  pixels.  Default  values  are  (2,6,2,4)  in  640  mode  and  (2,4,2,2) 
in  320  mode.  Each  indentation  coordinate  may  be  specified 
individually.  In  order  to  assert  the  default  for  any  coordinate,  specify 
its  value  as  $FFFF. 

vertBar  Handle  of  the  vertical  scroll  bar  to  use  for  the  TextEdit  window.  If  you 

do  not  want  a  scroll  bar  at  all,  then  set  this  field  to  NIL,  If  you  want 
TextEdit  to  create  a  scroll  bar  for  you,  just  inside  the  right  edge  of  the 
boundary  rectangle  for  the  control,  then  set  this  field  to  $FFFFFFFF. 

vert  Amount  Specifies  the  number  of  pixels  to  scroll  whenever  the  user  presses  the 
up  or  down  arrow  on  the  vertical  scroll  bar.  In  order  to  use  the  default 
value  (9  pbcels),  set  this  field  to  $0000. 

horzBar  MuSt  be  SCt  tO  NIL. 

horzAmount        MuSt  be  set  tO  0. 

styieRef         Reference  to  initial  style  information  for  the  text,  specified  in  a 

TEFormat  structure.  Bits  1  and  0  of  moreFiags  define  the  type  of 
reference  (pointer,  handle,  resource  ID)  to  the  structure.  In  order  to 
use  the  default  style  and  ruler  information,  set  this  field  to  NULL. 


textDescriptor 

Input  text  descriptor  that  defines  the  reference  type  for  the  initial 
text  (which  is  in  textRef )  and  the  format  of  that  text. 

textRef  Reference  to  initial  text  for  the  edit  window.  If  you  are  not  supplying 

any  initial  text,  then  set  this  field  to  NULL. 

textLength       If  textRef  is  a  pointer  to  the  initial  text,  then  this  field  must  contain 
the  length  of  the  initial  text.  For  other  reference  types,  this  field  is 
ignored— TextEdit  can  extract  the  length  from  the  reference  itself. 
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♦   Note:  YoumustspecifyoromitthetextDescriptor,  textRef,  andtextLength 
fields  as  a  group. 

maxchars         Maximum  number  of  characters  allowed  in  the  text.  If  you  do  not  want 
to  define  any  limit  to  the  number  of  characters,  then  set  this  field  to 
NULL. 

maxLines  Must  be  set  to  NULL. 


maxCharsPerLines 

Must  be  set  to  NULL. 

Must  be  set  to  NULL. 

Reference  to  the  color  table  for  the  text,  stored  inaTECoiorTabie 
structure.  Bits  2  and  3  of  moreFiags  define  the  type  of  reference 
stored  here. 

This  is  the  text  mode  used  by  QuickDraw  II  for  drawing  text.  See 
Chapter  16,  "QuickDraw  II,"  in  Volume  2  of  the  Toolbox  Reference  hr 
details  on  valid  text  modes. 

f  iiterProcPtr  Pointer  to  a  filter  routine  for  the  control.For  more  information  about 
TextEdit  filter  procedures,  see  "Generic  filter  procedure".  If  you  do 
not  want  to  use  a  filter  routine  for  the  control,  set  this  field  to  NIL. 


maxHeight 
colorRef 

drawMode 
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TERuler 

Defines  the  characteristics  of  a  TextEdit  ruler. 

The  TEGetRuier  and  TESetRuier  tool  calls  allowyou  to  obtain  and  set  the  ruler 
information  for  a  TextEdit  record. 

■   Figure  494     TERuier  layout 


$00 
$02 
$04 
$06 
$08 
$0A 
$0E 

$12 
$14 


lef tMargln 

leftlndent 

rightMargln 

just 

extraLS 

flags 

userData 

tabType 

•  theTabs 

tabTerminator 

Word 
Word 
Word 
Word 
Word 
Word 

Long 
Word 


lef  tMargin       Specifies  the  number  of  pixels  to  indent  from  the  left  edge  of  the  text 
rectangle  (viewRect  in  TERecord)  for  all  text  lines  except  those 
that  start  paragraphs. 

leftlndent       Specifies  the  number  of  pixels  to  indent  from  the  left  edge  of  the  text 
rectangle  (viewRect  in  TERecord)  for  text  lines  that  start 
paragraphs. 

rightMargln     Maximum  line  length,  expressed  as  the  number  of  pkels  from  the  left 
edge  of  the  text  rectangle  (viewRect  in  TERecord). 
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just  Text  justification; 

0  Left  justification— all  text  lines  start  flush  with  left  margin 
-1  Right  justification — all  text  lines  start  flush  with  right  margin 

1  Center  justification— all  text  lines  are  centered  between  left  and 
right  margins 

2  Full  justification — text  is  blocked  flush  with  both  left  and  right 
margins;  TextEdit  pads  spaces  with  extra  pixels  to  fully  justify 
the  text 

extraLS  Line  spacing,  expressed  as  the  number  of  pixels  to  add  between  lines 

of  text.  Negative  values  result  in  text  overlap. 

flags  Control  flags: 

Reserved  bit  15       Must  be  set  to  0 

f Equal Line Spacing 

bit  14  Must  be  set  to  0 

f  Showlnvisibles    bit  13  Must  be  set  to  0 

Reserved  bits  0-12  Must  be  set  to  0 

userData  Application-specific  data. 

tabType  Specifies  the  type  of  tab  data  that  follows: 

0  No  tabs  are  set— tabType  is  the  last  field  in  the  structure 

1  Regular  tabs— tabs  are  set  at  regular  pbcel  intervals,  specified  by 
the  value  of  the  tabierminator  field;  theTabs  is  omitted 
from  the  structure 

2  Absolute  tabs— tabs  are  set  at  absolute,  irregular  pbcel  locations; 
theTabs  defines  those  locations;  tabTerminator  marks  the 
end  of theTabs 

theTabs  If  tabType  is  set  to  2,  then  this  is  an  array  of  Tabitem  structures 

defining  the  absolute  pbcel  positions  for  the  various  tab  stops.  The 
tabTerminator  field,  with  a  value  of  $FFFF,  marks  the  end  of  this 
array.  For  other  values  of  tabType,  this  field  is  omitted  from  the 
structure. 

tabTerminator  If  tabType  is  set  to  0,  then  this  field  is  omitted  from  the  structure.  If 
tabType  is  set  to  1,  then  theTabs  is  Omitted,  and  this  field  contains 
the  number  of  pixels  corresponding  to  the  tab  interval  for  the  regular 
tabs.  If  tabType  is  set  to  2,  then  tabTerminator  is  set  tO  $FFFF, 
and  marks  the  end  of  theTabs  array. 
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TEStyle 

This  structure  defines  the  font  and  color  characteristics  of  a  style  for  text  in  the  TextEdit 
record. 

The  TEFormat  Structure  contains  one  or  more  TEStyie  structures,  each  of  which  defines 
a  unique  text  style  used  somewhere  in  the  record  text. 


■   Figure  49-5     TEStyie  layout 


$00 

font  ID 

Long 

$04 

f oreColor 

Word 

$06 

backColor 

Word 

$08 

userData 

Long 

font  ID  Font  Manager  font  ID  record  identifying  the  font  for  the  text.  See 

Chapter  8,  "Font  Manager,"  in  the  Toolbox  Reference  for  more 
information  about  font  IDs. 

f  oreColor        Defines  the  foreground  color  for  the  text.  This  is  a  TextEdit  color 
word,  as  described  in  "TECoiorTabie"  in  this  chapter. 

backColor        Defines  the  background  color  for  the  text.  This  is  a  TextEdit  color 
word,  as  described  in  "TECoiorTabie"  in  this  chapter. 


userData 


Application-Specific  data. 
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Low-level  TextEdit  structures 

TextEdit  uses  several  other  structures  for  its  internal  processing.  Typically,  your 
application  should  not  manipulate  these  structures.  In  addition,  if  your  program  does 
modify  data  in  these  structurers,  you  should  be  careful  to  maintain  the  correct 
relationships  between  fields  that  affect  other  TextEdit  structures. 

TERecord 

This  is  the  main  structure  for  a  TextEdit  record.  The  tensw  tool  call  creates  this  stmcture 
based  partially  on  the  information  specified  in  the  TEParamBiock  you  supply  to  that 
call.  In  most  cases,  your  program  does  not  need  to  direcdy  access  fields  in  this  structure. 
However,  in  order  to  use  such  advanced  features  as  custom  word-wrap  routines,  your 
application  will  have  to  modify  the  TERecord. 

Note  that  this  section  only  describes  those  TERecord  fields  that  are  currently  defined 
and  available  to  application  programs.  Your  program  should  assume  that  there  are  more 
fields  beyond  those  described  here,  and  should  not  try  to  directly  move  or  copy  a 
TERecord. 

Most  TextEdit  tool  calls  require  a  handle  to  a  TERecord  as  an  entry  parameter. 
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Figure  49-6     TERecord  layout 
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ctrlNext 


InPort  -  Long 
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boundsReot         :  Rectangle 


—  lastErrorCode 


—  filterProc 


ctrlFlag 


ctrlHllite 
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—        ctrlRefCon  — 


col or Re f  -  Long 
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textLength        -  Long 
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$30 


$38 


$3C 


continued 


biockList        •  TextList 


Ctrl  ID         -  Long 


ctrlMoreFlags      -  Word 


[_       ctrlVersion       -|  Word 

$40 


viewRect 


$48 

$4C 
$58 
$64 

$68 

$6C 
$6E 

$72 


-  totalHeight 


Rectangle 


Long 


lineSuper         :  SuperHandle 


styleSuper         :  SuperHandle 


styleList 


rulerList 


-  llneAtEndFIag 


—     selectionStart  — 


—  selectlonEnd 


continued 


Long 

Long 
Word 
Long 

Long 
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$76 
$78 
$7A 


—     selectlonState  — 


$7E 
$80 


continued 


selectionActlve  — 


—  caretTime 


—    nullStyleActive  — 


Word 
Word 

Long 
Word 


nullStyle  ■  TEStyle 


$8C 

$90 
$92 

$96 

$9A 

$9E 
$A0 

$A4 


-      topTextOffset      -  Long 


—      vertScrollBar      —  Long 


—      vertScrollPos      —  Long 


topTextVPos        —  Word 


—      vertScrollMax      —  Long 


—  vertScrollAmount  —  Word 


—      horzScrollBar      —  Long 


—      horzScrollPos      —  Long 


continued 


49-50    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3  Beta  Draft 


30  August  1989 


$A8 

continued 

horzScrollMax 

Long 

$AC 

horzScrollAmount 

Word 

$AE 

growBoxHandle 

Long 

$B2 

maximumChars 

Long 

$B6 

maximumLines 

Long 

$BA 

maxCharsPerLine 

Word 

$BC 

maximumHeight 



Word 

$BE 

textDrawMode 

Word 

$C0 

wordBreakHook 

Long 

$C4 

wordWrapHook 

Long 

$C8 

keyFilter 

Long 

$CC 

theFiiterRect      '■  Rectangle 


continued 
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continued 

$D4 

—      theBuf f erVPos  — 

Word 

$D6 

—      theBuf ferHPos  — 

Word 

$D8 

theKeyRecord         •  KeyRecord 


$e6 

$EA 
$EC 
$EE 


cachedSelcOffset   —  Long 


-     cachedSelcVPos     -J  Word 

Word 


cachedSelcHPos 


ouseRect  :  Rectangle 


$f6 

mouseTime 

Long 

$FA 
$FC 

mouseKind 

Word 

lastCllck 

Long 

$100 

savedHPos 

Word 

$102 

anchorPolnt 

Long 

ctrlNext 

inPort 

boundsRect 

ctrlFlag 


ctllnvis 
Reserved 


Handle  of  next  control  in  the  system-maintained  control  list. 

Pointer  to  the  GrafPort  for  this  TextEdit  record. 

Boundary  rectangle  for  the  record,  which  surrounds  the  text  window  as 
well  as  its  scroll  bars  and  outline. 

Control  flags  for  the  TextEdit  record.  TextEdit  obtains  this  field  from 
the  low-order  byte  of  the  flags  field  in  the  TEParamBiock  passed 
to  TENew.  The  following  flags  are  defined: 

bit  7         l=invisible,  0=visible 
bits  0-6     Must  be  set  to  0 
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ctrlHilite 


Reserved 


lastErrorCode  The  last  error  code  generated  by  TextEdit.  Note  that  this  code  may 
have  been  returned  by  either  a  control  definition  procedure  or  from  a 
TextEdit  tool  call. 


ctrlProc 

ctrlAction 
f ilterProc 

ctrlRef Con 
colorRef 

textFlags 


Must  be  set  to  $85000000.  Identifies  this  as  a  TextEdit  control  to  the 
system. 

Reserved 

Pointer  to  the  generic  filter  procedure  for  the  record.  If  there  is  no 
filter  procedure,  this  field  is  set  to  NULL.  See  "Generic  filter 
procedure"  for  information  about  generic  filter  procedures. 

Application-defined  value. 

Reference  to  the  TECoioriabie  for  the  record.  Bits  2  and  3  in 
ctriMoreFiags  define  the  type  of  reference  stored  here. 

Control  flags  specific  to  TextEdit.  The  system  derives  this  field  from 
the  textFlags  field  in  the  TEParamTabie  Structure  passed  to 
TENew  when  a  new  TextEdit  record  is  created.  The  following  flags  are 
defined: 


fNotControl 


f SingleFormat 
f SingleStyle 


f NoWordWrap 


fNoScroll 


bit  31 


bit  30 
bit  29 


bit  28 


bit  27 


Indicates  whether  the  the  TextEdit  record  to  be 

created  is  for  a  control: 

1  -  TextEdit  record  is  not  a  control 

0  -  TextEdit  record  is  a  control 
Must  be  set  to  1 

Allows  you  to  restrict  the  style  options  available  to 
the  user: 

1  -  Allow  only  one  style  in  the  text 

0  -  Do  not  restrict  the  number  of  styles  in  the  text 
Allows  you  to  control  TextEdit  word  wrap  behavior: 

1  -  Do  not  word  wrap  the  text;  only  break  lines  on  CR 
($0D)  characters 

0  -  Perform  word  wrap  to  fit  the  ruler 
Controls  user  access  to  scrolling: 

1  -  Do  not  allow  either  manual  or  auto-scrolling 
0  -  Scrolling  permitted 
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f Readonly 


f  SmartCutPaste      bit  25 


f TabSwitch 


fDrawBounds 


f  ColorHilight  bit  22 
fGrowRuler  bit  21 


bit  26        Restricts  the  text  in  the  window  to  read-only 

operations  (copying  from  the  window  will  still  be 
allowed): 

1  -  No  editing  allowed 

0  -  Editing  permitted 

Controls  TextEdit  support  for  smart  cut  and  paste: 

1  -  Use  smart  cut  and  paste 

0  -  Do  not  use  smart  cut  and  paste 
bit  24       Defines  behavior  of  the  Tab  key: 

1  -  Tab  to  next  control  in  the  window 

0  -  Tab  inserted  in  TextEdit  document 

bit  23       Tells  TextEdit  whether  to  draw  a  box  around  the  edit 
window,  just  inside  boundsRect.  The  pen  for  this 
rectangle  is  two  pbcels  wide  and  one  pixel  high 

1  -  Draw  rectangle 

0  -  Do  not  draw  rectangle 
Must  be  set  to  0. 

Tells  TextEdit  whether  to  resize  the  ruler  in  response 
to  the  user  resizing  the  edit  window.  If  set  to  1, 
TextEdit  will  automatically  adjust  the  right  margin 
value  for  the  ruler: 

1  -  Resize  the  ruler 
0  -  Do  not  resize  the  ruler 


fDrawInactiveSelection 

bit  19 


fDisableSelection 

bit  20       Controls  whether  user  can  select  text: 
1  -  User  cannot  select  text 

0  -  User  can  select  text 

Controls  how  inactive  selected  text  is  displayed; 

1  -  TextEdit  draws  a  box  around  inactive  selections 
0  -  TextEdit  does  not  display  inactive  selections 

Reserved  bits  0-18    Must  be  set  to  0 

textLength      Number  of  bytes  of  text  in  the  record.  Your  program  must  not  modify 
this  field. 

biockList        Cached  link  into  the  linked  list  of  TextBiock  stmctures,  which 

contain  the  actual  text  for  the  record.  The  actual  Text  List  structure 
resides  here.  Your  program  must  not  modify  this  field. 


CtrllD 


Application-assigned  ID  for  the  TextEdit  control. 
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ctriMoreFiags  More  control  flags.  TextEdit  obtains  the  data  for  this  field  from  the 
moreFlags  field  of  the  TEParamBlock  Structure  passed  to  TENew 
when  a  new  TextEdit  record  is  created.  The  following  flags  are 
defined: 


fCtlTarget  bit  15 


fCtlCanBeTarget  bit  14 

fCtlWantsEvents  bit  13 

fCtlProcNotPtr  bit  12 

fTellAboutSize  bit  11 


fCtllsMultiPart     bit  10 
Reserved  bits  4-9 

Color  Table  Reference  bits  2-3 


Reserved 

ctrlVersion 

viewRect 


totalHeight 
lineSuper 

styleSuper 

styleList 

rulerList 


bits  0-1 
Reserved 


Indicates  whether  this  TextEdit  record  is  the  current 
target  of  user  actions.  Must  be  set  to  0  when  creating 
a  TextEdit  record. 
Must  be  set  to  1 
Must  be  set  to  1. 
Must  be  set  to  1 

If  set  to  1,  TextEdit  will  create  a  size  box  in  the 
bottom  right  corner  of  the  window.  Whenever  the 
window  is  resized,  the  edit  text  will  be  resized  and 
redrawn. 
Must  be  set  to  1 
Must  be  set  to  0 

Defines  type  of  reference  in  coiorRef ; 

00  -  color  table  reference  is  pointer 

01  -  color  table  reference  is  handle 

10  -  color  table  reference  is  resource  ID 

11  -  invalid  value 
Must  be  set  to  0 


Boundary  rectangle  for  the  text,  within  the  rectangle  defined  in 
boundsRect,  which  surrounds  the  entire  record,  including  its 
associated  scroll  bars  and  outline. 

Total  height  of  the  text  in  the  TextEdit  record,  in  pixels. 

Cached  link  into  the  linked  list  of  superBiock  structures  that  define 
the  text  lines  in  the  record. 

Cached  link  into  the  linked  list  of  SuperBiock  structures  that  define 
the  styles  for  the  record. 

Handle  to  array  of  TEStyie  structures,  containing  style  information 
for  the  record.  The  array  is  terminated  with  a  long  set  to  $FFFFFFFF. 

Handle  to  array  of  TERuier  structures,  defining  the  format  rulers  for 
the  record.  Note  that  only  the  first  ruler  is  currently  used  by  TextEdit, 
The  array  is  terminated  with  a  long  set  to  $FFFFFFFF. 
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lineAtEndFiag  Indicates  whether  the  last  character  was  a  line  break.  If  so,  this  field  is 
set  to  $FFFF. 

selections tart 

Starting  text  offset  for  the  current  selection.  Must  always  be  less  than 
selectionEnd. 

seiectionEnd   Ending  text  offset  for  the  current  selection.Must  always  be  greater 
than  selectionStart. 

selectionActive 

Indicates  whether  the  current  selection  (defined  by 
selectionStart  and  selectionEnd)  is  active: 

$0000  Active 
$FFFF  Inactive 

seiectionstate      Contains  State  information  about  the  current  selection  range: 

$0000  Off  screen 

$FFFF  Onscreen 

caretTime        Blink  interrval  for  caret,  expressed  in  system  ticks. 

nullStyleActive 

Indicates  whether  the  null  style  is  active  for  the  current  selection: 

$0000  Do  not  use  null  style  when  inserting  text 

$FFFF  Use  null  style  when  inserting  text 

nuiistyie        TEStyle  Structure  defining  the  null  style.  This  may  be  the  default 
style  for  newly  inserted  text,  depending  upon  the  value  of 

nullStyleActive. 

topTextof  f  set  Text  offset  into  the  record  corresponding  to  the  top  line  displayed  on 
the  screen. 

topTextvPos     Difference,in  pbcels,  between  the  topmost  vertical  scroll  position 
(corresponding  to  the  top  of  the  vertical  scroll  bar)  and  the  top  line 
currently  displayed  on  the  screen.  This  is,  essentially,  the  vertical 
position  of  the  display  window  in  the  text  for  the  record. 

vertScroiiBar  Handle  to  the  vertical  scroll  bar  control  record. 

vertScroiiPos  Current  position  of  the  vertical  scroll  bar,  in  units  defined  by 
ve  rt  S  c  r ol lAmount . 
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♦  Note:  that  while  TextEdit  supports  vertscroiiPos  as  a  long,  standard  Apple  IlGS 
scroll  bars  support  only  the  low-order  word.  This  leads  to  unpredictable  scroll  bar 
behavior  when  editing  large  documents. 

vertscroiiMax  Maximum  allowable  vertical  scroll,  in  units  defined  by 

vertScrollAmount. 

vertScrollAmount 

Number  of  pixels  to  scroll  on  each  vertical  arrow  click. 

horzScroiiBar  Handle  to  the  horizontal  scroll  bar  control  record.  Currently  not 
supported 

horzScroiiPos  Current  position  of  the  horizontal  scroll  bar,  in  units  defined  by 
horzScroiiAmount.  Currently  not  supported 

horzScroiiMax  Maximum  allowable  horizontal  scroll,  in  units  defined  by 
horzScroiiAmount.  Currently  not  supported 

horzScroiiAmount 

Number  of  pixels  to  scroll  on  each  horizontal  arrow  click.  Currently  not 
supported. 

growBoxHandie  Handle  of  size  box  control  record, 
maximumchars    Maximum  number  of  characters  allowed  in  the  text. 
maximumLines    Maximum  number  of  lines  allowed  in  the  text.  Currently  not  supported. 

maxCharsPerLine 

Currently  not  supported. 

maximumHeight  Maximum  text  height,  in  pixels.  This  value  allows  applications  to  easily 
constrain  text  to  a  display  window  of  a  known  height.  Currently  not 
supported. 

textDrawMode    QuickDraw  II  drawing  mode  for  the  text.  See 

Chapter  16,  "QuickDraw  II,"  in  the  Toolbox  Reference  for  more 
information  on  QuickDraw  II  drawing  modes. 

wordBreakHook  Pointer  to  the  routine  that  handles  word  breaks.  See  "Word  break 
hook"  earlier  in  this  chapter  for  information  about  word  break 
routines.  Your  program  may  modify  this  field. 
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wordwrapHook  Pointer  to  the  routine  that  handles  word  wrap.  See  "Word  wrap  hook" 
earlier  in  this  chapter  for  information  about  word  wrap  routines.  Your 
program  may  modify  this  field. 

keyFiiter        Pointer  to  the  keystroke  filter  routine.  See  "Keystroke  filter 

procedure"  earlier  in  this  chapter  for  information  about  keystroke 
filter  routines.  Your  program  may  modify  this  field. 

theFiiterRect  Defines  a  rectangle  used  by  the  generic  filter  procedure  for  some  of  its 
routines.  See  "Generic  filter  procedure"  earlier  in  this  chapter  for 
information  about  generic  filter  procedures  and  their  routines.  Your 
program  may  modify  this  field. 

theBuf  f  erVPos  Vertical  component  of  the  current  position  of  the  buffer  within  the 
port  for  the  TextEdit  record,  expressed  in  the  local  coordinates 
appropriate  for  that  port.  This  value  is  used  by  some  generic  filter 
procedure  routines.  See  "Generic  filter  procedure"  for  information 
about  generic  filter  procedures  and  their  routines.  Your  program  may 
modify  this  field. 

theBuf  ferHPos  Horizontal  component  of  the  current  position  of  the  buffer  within  the 
port  for  the  TextEdit  record,  expressed  in  the  local  coordinates 
appropriate  for  that  port.  This  value  is  used  by  some  generic  filter 
procedure  routines.  See  "Generic  filter  procedure"  earlier  in  this 
chapter  for  information  about  generic  filter  procedures  and  their 
routines.  Your  program  may  modify  this  field. 

theKeyRecord   Parameter  block,  in  KeyRecord  format,  for  the  keystroke  filter 
routine.  Your  program  may  modify  this  field. 

cachedSelcOf f set 

Cached  selection  text  offset.  If  this  field  is  set  to  $FFFFFFFF,  then  the 
cache  is  invalid  and  will  be  recalculated  when  appropriate. 

cachedSelcVPos 

Vertical  component  of  the  cached  buffer  position,  expressed  in  local 
coordinates  for  the  output  port. 

cachedSelcHPos 

Horizontal  component  of  the  cached  buffer  position,  expressed  in 
local  coordinates  for  the  output  port. 


49-58    Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


mouseRect 


mouseTime 

mouseKind 

0 
1 
2 

lastClick 
savedHPos 

anchorPoint 


Boundary  rectangle  for  multiclick  mouse  commands.  If  the  user  clicks 
the  mouse  more  than  once  within  the  region  defined  by  this  rectangle 
within  the  time  period  defined  for  multiclicks,  then  TextEdit 
interprets  those  clicks  as  multiclick  sequences  (double-  or  triple- 
clicks).  The  user  sets  the  time  period  with  the  Control  Panel. 

System  tickcount  when  the  user  last  released  the  mouse  button. 

Type  of  last  mouse  click: 

Single  click 

Double-click 

Triple-click 

Location  of  last  user  mouse  click. 

Cached  horizontal  character  position.  TextEdit  uses  this  value  to 
manage  where  it  should  display  the  caret  on  a  line  when  the  user 
presses  the  up  or  down  arrow. 

Defines  the  character  from  which  the  user  began  to  select  text  for  the 
current  selection.  When  TextEdit  expands  the  current  selection  (as  a 
result  of  user  keyboard  or  mouse  commands,  or  at  the  direction  of  a 
custom  keystroke  filter  procedure),  it  always  does  so  from  the 
anchorPoint,  not  selectionStart  or  selectionEnd. 


KeyRecord 

Defines  the  entry  and  exit  parameter  block  for  the  keystroke  filter  procedure  for  a 
TextEdit  record.  On  entry  to  the  filter  procedure,  TextEdit  sets  up  this  structure  with  the 
information  necessary  to  process  the  keystroke.  On  exit,  the  filter  procedure  returns  the 
processed  keystroke  and  any  other  status  information  in  this  same  structure.  For 
complete  information  about  the  TextEdit  keystroke  filter  procedure  and  the  use  of  these 
fields,  see  "Keystroke  filter  procedure"  eariier  in  this  chapter. 

The  KeyRecord  for  a  TextEdit  record  resides  in  the  appropriate  TERecord. 
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u   Figure  49-7     KeyRe cord  layout 
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Character  code  of  the  character  to  translate.  The  low-order  byte  of 
thechar.contains  the  key  code  for  the  character;  the  high-order  byte 
is  ignored. 

On  input,  contains  the  state  of  the  modifier  keys  when  the  character 
in  theChar  was  generated.  This  is  an  Event  Manager  modifier  word, 
as  described  in  Chapter  7,  "Event  Manager,"  of  the  Toolbox  Reference. 
On  output,  the  keystroke  filter  procedure  may  change  the  setting  of 
these  flags. 


thelnputHandle 

On  input,  contains  a  handle  to  a  copy  of  the  keystroke  in  theChar. 
On  output,  the  keystroke  filter  procedure  may  modify  the  size  and 
content  of  the  data  referred  to  by  this  handle. 

cursorOf  f  set    For  some  operations,  the  keystroke  filter  routine  sets  this  field  with  a 
new  cursor  text  offset. 
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theOpCode 


opNormal 


opNothing 
opReplaceText 


On  return  from  the  filter  routine,  this  field  contains  an  operation  code 
indicating  what  TextEdit  is  to  do  next  and  how  it  is  to  interpret  the 
KeyRecord: 


$0000 


$0001 
$0002 


opMoveCursor  $0003 
opExtendCursor  $0004 


opCut 
opCopy 
opPaste 
opClear 


$0005 
$0006 
$0007 
$0008 


TextEdit  performs  its  standard  processing  on  the 
character  stored  in  the  location  referred  to  by 

thelnputHandle 

TextEdit  ignores  the  keystroke 

TextEdit  inserts  the  text  referred  to  by 

thelnputHandle  in  place  of  the  current  selection 

in  the  record;  if  there  is  no  current  selection,  TextEdit 

inserts  the  text  at  the  current  insertion  point— if 

thelnputHandle  has  0  si2e,  TextEdit  deletes  the 

current  selection  and  inserts  nothing 

TextEdit  moves  the  cursor  to  the  location  specified 

by  cursorOf f set 

TextEdit  extends  the  current  selection  from  its 
anchor  point  to  the  location  specified  by 
cursorOf f set 

TextEdit  copies  the  current  selection  to  the  desk 

scrap  then  clears  the  selection 

TextEdit  copies  the  current  selection  to  the  desk 

scrap 

TextEdit  inserts  the  contents  of  the  desk  scrap  in 
place  of  the  current  selection 
TextEdit  clears  the  current  selection 
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Stylel tern 

The  TEFormat  stoicture  contains  an  array  of  styieitem  substructures,  which  define  the 
text  characters  that  use  a  particular  style.  Each  element  of  this  array  refers  to  the  style 
information  for  a  run  of  characters.  Taken  consecutively,  the  array  of  styieitem 
structures  completely  defines  the  styles  for  the  entire  record. 


■   Figure  49-8     styieitem  layout 
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length 


The  total  number  of  text  characters  that  use  this  style.  These 
characters  begin  where  the  previous  styieitem  left  off.  Value  of 
$FFFFFFFF  indicates  an  unused  entry. 


offset 


Offset,  in  bytes,  into  theStyieList  array  in  the  TEFormat  record 
to  the  TEStyie  record  which  defines  the  characteristics  of  the  style 
in  question. 
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SuperBlock 

SuperBiock  stnictures  define  linked-lists  of  TextEdit  control  information  items.  These 
control  information  items  may  relate  to  styles  or  to  line  start  locations,  and  are  defined  by 
the  Superitem  substructure.  A  superHandie  substructure  provides  address 
information  into  a  chain  of  SuperBlock  stmctures.  The  TERecord  contains  a  number 
of  SuperHandles. 


■   Figure  49-9     Supersiock  layout 
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nextHandie      Handle  to  the  next  SuperBlock  in  this  chain  of  blocks.  A  value  of 
NIL  indicates  the  end  of  the  chain. 

prevHandle       Handle  to  the  previous  SuperBlock  in  this  chain  of  blocks.  A  value 
of  NIL  indicates  the  beginning  of  the  chain. 

textLength      The  number  of  characters  of  text  referred  to  by  theltems . 

Reserved  Reserved 

theltems  Array  of  Superltems  for  this  SuperBlock.  The  textLength  field 

contains  the  total  length  of  the  characters  defined  by  these  items. 
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SuperHandle 

Identifies  the  current  position  within  a  chain  of  SuperBiocks.  This  substructure 
contains  both  byte  offset  and  index  information.  The  cachedof  f  set  field  contains  the 
offset  into  the  text  identified  by  the  cached  supentem.  The  cachedindex  field 
contains  the  byte  offset  to  the  Superitem  within  its  SuperBiock.  The  TERecord 
contains  several  SuperHandies. 

■   Figure  49-10    superHandie  layout 


$00 

cachedHandle 

Long 

$04 

cachedOf f set 

Long 

$08 

cachedlndex 

Word 

$0A 

itemsPerBlock 

Word 

cachedHandle    Handle  tO  the  SuperBiock  containing  the  current  Superitem. 

cachedof  f  set    Byte  offset  to  the  current  character  within  the  text  identified  by  the 
cached  superitem. 

cachedlndex     Byte  offset  to  the  Start  of  the  current  superitem  within  the  array  of 
Super  I  terns  Stored  in  the  SuperBiock  referred  to  by 
cachedHandle. 

itemsPerBlock  Indicates  the  number  of  Supentems  stored  in  each  SuperBiock. 
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SuperXtem 

Defines  an  individual  item  witiiin  a  SuperBiock. 
■   Figure  49-11    supentem  layout 


length  Specifies  the  number  of  text  characters  in  the  TextEdit  record  that  are 

affected  by  this  Super  item.  A  value  of  $FFFFFFFF  indicates  that  this 
item  is  not  currently  used. 

data  Contains  the  actual  data  for  the  item. 
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Tabltem 

Contains  information  defining  an  absolute  tab  position,  expressed  as  a  pixel  offset  from 
the  left  margin  of  the  text  rectangle  (viewRect  of  the  TERecord).  The  TERuier 
structure  contains  an  array  of  Tabitems  whenever  the  user  has  defined  absolute  tabs. 


■   Figiire  49-12    Tabitem  layout 
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tabKind  Must  be  set  to  $0000. 

tabData  Location  of  the  absolute  tab,  expressed  as  the  number  of  pbcels  to 

indent  from  the  left  edge  of  the  text  rectangle  (viewRect  of 

TERecord). 
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TextBlock 

Contains  the  actual  text  for  the  record.  The  TextBiock  substructure  defines  a  linked-list 
which  stores  the  text.  A  TextList  substructure  within  the  TERecord  contains  access 
information  into  the  chain  of  TextBiocks  for  the  TextEdit  record.  The  TextBiock 
chain  stores  the  text  for  the  TextEdit  record  in  sequential  order.  That  is,  the  first 
TextBiock  contains  the  first  block  of  text,  the  second  TextBiock  contains  the  next 
block  of  text,  and  so  on. 


■   Figure  49-13    TextBiock  layout 
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nextHandle       Handle  to  the  next  TextBiock  in  the  chain  of  blocks  for  this  text 
record.  A  value  of  NIL  indicates  the  end  of  the  chain. 

prevHandle       Handle  to  the  previous  TextBiock  in  the  chain  of  blocks  for  this 
text  record.  A  value  of  NIL  indicates  the  beginning  of  the  chain. 

textLength      The  number  of  text  bytes  stored  at  theText. 

flags  Reserved. 

Reserved  Reserved 

theText  Text  for  the  record.  The  textLength  field  specifies  the  length  of 

this  array. 
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TextList 

Identifies  the  current  position  within  the  text  for  the  record,  which  is  stored  in 
TextBiocks.  The  TERe cord  contains  a  TextList  substructure. 


■   Figure  49-14   TextList  layout 
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cachedHandle    Handle  to  the  TextBiock  containing  the  text  corresponding  to  the 
current  location. 

cachedOf  f  set     Byte  offset  within  the  TextBiock  referred  to  by  cachedHandle 
corresponding  to  the  current  location. 
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TextEdit  housekeeping  routines 

The  following  sections  describe  the  standard  housekeeping  calls  in  the  TextEdit  Tool  Set. 

TEBootlnit  $0122 

Initializes  TextEdit;  called  only  by  the  Tool  Locator. 
Parameters  None 
Errors  None 


Chapter  49  TextEdit  49-69 


Apple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


TEStartUp  $0222 

Starts  up  the  TextEdit  tool  set,  and  prepares  TextEdit  for  use  by  an  application  by 
allocating  memory  and  formatting  direct-page  space.  Application  programs  must  issue 
this  call  before  any  other  TextEdit  tool  calls,  Before  exiting,  applications  that  issue  the 
TEStartUp  call  must  call  TEShutDown  to  dc-initialized  TextEdit. 

Parameters 

Stack  before  call 

Previous  contents 


directPage 


userlD 


Word— Application's  User  ID  (obtained  at  program  start  time) 
Word— Address  of  one  page  of  direct-page  memory 


<— SP 


Stack  after  call 


PreiHous  contents 


<— SP 


Errors 


$2201  teAlreadyStarted 
Memory  Manager  errors 


TextEdit  has  already  been  started 
Returned  unchanged 


C 


extern  pascal  void  TEStartUp (userlD,  directPage); 


Word 


userlD,  directPage; 
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TEShutDown  $0322 

Frees  memory  used  by  TextEdit  on  behalf  of  an  application,  not  including  individual 
TextEdit  records— it  is  the  application's  responsibility  to  issue  the  tekhi  tool  call  at 
the  end  of  each  TextEdit  record.  Every  application  that  uses  TextEdit  must  issue  this  call 
before  exiting.  During  application  initialization,  applications  that  use  TextEdit  must 
issue  the  TEStartup  tool  call  before  any  other  TextEdit  calls. 

Parameters 

Stack  before  call 


Previous  contents 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


$2202 


teNotStarted 


TextEdit  has  not  been  started 


C 


extern  pascal  void  TEShutDown {) ; 
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TEVersion  $0422 

Retrieves  the  Resource  Manager  version  number.  This  call  returns  valid  information  if 
TextEdit  has  been  loaded;  the  tool  set  need  not  be  active.  The  versionlnfo  result  will 
contain  the  information  in  the  standard  format  defined  in  Appendix  A,  "Writing  Your  Own 
Tool  Set,"  in  Volume  2  of  die  Toolbox  Reference. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


Word— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


versionlnfo 


Word— TextEdit  version  number 


<— SP 


Errors 


None 


c 


extern  pascal  Word  TEVersion () ; 


TEReset  $0522 


Resets  TextEdit;  called  only  when  the  system  is  reset. 


Parameters 


None 


Errors 


None 
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TEStatus  $0622 

Returns  a  flag  indicating  whether  TextEdit  is  active.  If  TextEdit  has  not  been  loaded,  your 
program  receives  a  Tool  Locator  error  (tooiNotFoundErr). 

♦  Note:  If  your  program  issues  this  call  in  assembly  language,  initialize  the  result  space  on 
the  stack  to  NIL.  Upon  return  from  TEStatus,  your  program  need  only  check  the 
value  of  the  returned  flag.  If  TextEdit  is  not  active,  the  returned  value  will  be  FALSE 
(NIL). 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Word— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


activeFlag 


Word— Boolean;  TRUE  if  TextEdit  is  active 


<— SP 


Errors 


None 


C 


extern  pascal  Word  TEStatus (); 
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TextEdit  tool  calls 

The  following  sections  describe  the  TextEdit  tool  calls,  in  order  by  call  name. 


TEActivate  $0F22 

Makes  the  specified  TextEdit  record  active— that  is,  makes  that  record  the  target  of  user 
keystrokes.  TextEdit  highlights  the  current  selection  or  displays  the  caret,  as  appropriate. 
User  editing  activity  now  applies  to  this  TextEdit  record. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls  with  TaskMaster,  it  should  not  issue  this  caO;  TaskMaster 
manages  the  control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long— Handle  of  TERecord  in  menwry 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$2202 
$2203 


<— SP 

teNotStarted 
telnvalidHandle 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 
TERecord 


extern  pascal  void  TEActivate (teHandle) ; 
Long  teHandle; 
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TEClear  $1922 

Clears  the  current  selection  in  the  active  TextEdit  record  and  redraws  the  screen.  If  there  is 
no  current  selection,  then  this  call  does  nothing  and  returns  immediately.  This  call  does  not 
affect  the  desk  scrap. 

Note  that  this  call  does  not  generate  any  update  events;  it  directly  redraws  the  active 
record. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls  and  TaskMaster,  it  should  not  issue  this  call;  TaskMaster 
manages  the  control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long — Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


Errors 
C 

teHandle 


<— SP 

$2202      teNotstarted  TextEdit  has  not  been  started 

extern  pascal  void  TEClear (teHandle) ; 


Long 


teHandle; 


Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEClick  $1122 

Tracks  the  mouse  within  a  TextEdit  record,  selecting  aO  text  that  it  passes  over  until  the 
user  releases  the  mouse  button.  If  the  user  holds  down  the  Shift  key,  this  call  extends  the 
current  selection  to  include  the  new  text,  TextEdit  automatically  scrolls  the  text  in  the 
proper  direction  if  the  user  drags  the  mouse  outside  the  view  rectangle. 

This  call  handles  double-  and  triple-clicks  as  follows;  double-clicks  select  a  word,  dragging 
lengthens  or  shortens  the  selection  in  word  increments;  triple-clicks  select  a  line,  dragging 
lengthens  or  shortens  the  selection  in  line  increments. 

If  your  program  issues  this  call  for  a  TextEdit  record  that  is  not  currently  active,  TextEdit 
first  makes  that  record  active,  then  proceeds  to  track  the  mouse. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls  with  TaskMaster,  it  should  not  issue  this  call;  TaskMaster 
manages  the  control  automatically. 

Parameters 

Stack  before  call 

Previous  contents 

-  eventRecordPtr  -  Long— Pointer  to  event  record  for  the  mouse  click 

teHandle     -  Long— Handle  of  TERecord  in  memory 

<— SP 

Stack  after  call 


Previous  contents 


Errors 


$2202 
$2203 


<— SP 

teNotStarted 
telnvalidHandle 


Memory  Manager  errors 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 

TERecord 

Returned  unchanged 
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C  extern  pascal  void  TEClick (eventRecordPtr, 

teHandle) ; 

Pointer  eventRecordPtr; 
Long  teHandle; 

eventRecordPtr     Points  to  the  event  record  describing  the  mouse  click.  The  what, 

when,  where,  and  modifiers  fields  of  the  event  record  must  be  set. 
TextEdit  ignores  the  message  field.  For  information  on  the  format 
and  content  of  event  records,  see  Chapter  7,  "Event  Manager,"  in  the 
Toolbox  Reference. 
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TECompactRecord  $1728 

Compacts  all  the  TextEdit  data  structures  in  a  specified  TextEdit  record. 
TECompactRecord  reclaims  space  used  for  deleted  lines  and  style  items,  and  for  styles 
that  are  no  longer  referenced  from  the  text.  While  this  call  may  be  issued  by  any 
application  that  uses  TextEdit,  it  is  intended  to  be  used  from  within  an  out-of-memory 
routine  (see  Chapter  36,  "Memory  Manager  Update,"  in  this  book  for  information  about 
out-of-memory  routines  and  the  out-of-memory  queue). 

Note  that  your  program  may  not  pass  a  NULL  TextEdit  record  handle  to  this  tool  call. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long— Handle  of  TERecord  to  compact 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


teHandle 


<— SP 

$2202  teNotStarted 
Memory  Manager  errors 


TextEdit  has  not  been  started 
Returned  unchanged 


extern  pascal  void  TECompactRecord (teHandle) ; 

Long  teHandle; 

Specifies  the  TextEdit  record  for  the  operation. 
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TECopy  $1722 

Copies  the  current  selection  from  the  active  TextEdit  record  to  the  desk  scrap, 
destroying  the  previous  desk  scrap  contents.  This  call  copies  both  the  text  and  style 
information  to  the  scrap.  Note,  however,  that  if  there  is  no  current  selection,  then  this  call 
does  nothing,  and  does  not  affect  the  desk  scrap. 

This  call  does  not  automatically  scroll  to  the  current  selection. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

$2202  teNotStarted 
Memory  Manager  errors 


TextEdit  has  not  been  started 
Returned  unchanged 


extern  pascal  void  TECopy (teHandle) ; 


Long  teHandle; 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TECut  $1622 

Copies  the  current  selection  from  the  active  TextEdit  record  to  the  desk  scrap, 
destroying  the  previous  deslc  scrap  contents.  TECut  then  scrolls  to  the  beginning  of  the 
selection,  deletes  it,  and  then  redraws  the  screen.  This  call  copies  both  the  text  and  style 
information  to  the  scrap.  Note,  however,  that  if  there  is  no  current  selection,  then  this  call 
does  nothing,  and  does  not  affect  the  desk  scrap. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

$2202  teNotStarted 

Memory  Manager  errors 


TextEdit  has  not  been  started 
Returned  unchanged 


extern  pascal  void  TECut (teHandle) ; 


Long  teHandle; 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEDeactivate  $1022 

Deactivates  a  TextEdit  record.  Your  program  specifies  the  TERecord  for  the  record  in 
question.  TEDeactivate  changes  the  highlighting  for  the  current  selection  in  that  record 
to  show  that  it  is  inactive.  Any  user  editing  actions  (keystrokes,  cut  and  paste)  have  no 
effect  on  the  deactivated  record. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long— Handle  of  TERecord  in  memory 
<— SP 


Stack  after  call 


PretHous  contents 


Errors 


$2202 
$2203 


<— SP 

teNotStarted 
telnvalidHandle 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 
TERecord 


extern  pascal  void  TEDeactivate (teHandle) ; 


Long 


teHandle; 
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TEGetDefProc  $2222 

Returns  the  address  of  the  TextEdit  control  definition  procedure.  The  system  issues  this 
call  when  the  Control  Manager  starts  up  in  order  to  obtain  the  address  of  the  TextEdit 
control  definition  procedure.  This  call  is  not  intended  for  application  use. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


-    defProcPtr  - 


Long— Pointer  to  control  definition  procedure 


<— SP 


Errors 


None 


C 


extern  pascal  Pointer  TEGetDef Proc () ; 
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TEGetlnternalProc  $2622 

Returns  a  pointer  to  the  low-level  procedure  routine  for  TextEdit. 

This  call  is  reserved  for  future  use  by  application  programs  to  access  certain  low-level 
TextEdit  routines. 

Parameters 

Stack  before  call 

Previous  contents 


Space 


Long— Space  for  result 


<— SP 


Stack  after  call 


Previous  contents 


-  intemalProcPtr  - 


Long— Pointer  to  internal  low-level  procedure  routine 


<— SP 


Errors 


None 


C 


extern  pascal  Pointer  TEGetlnternalProc () ; 
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TEGetLastError  $2722 

Returns  the  last  error  code  generated  for  a  TextEdit  record.  Your  program  specifies  the 
TERecord  for  the  appropriate  record  and  a  flag  indicating  whether  to  clear  the  last  error 
code  after  the  call.  TextEdit  then  returns  the  last  error  code  for  that  record,  and,  if 
requested,  clears  the  last  error  field. 

Parameters 

Stack  before  call 

Previous  contents 

Space  Word— Space  for  result 

clearFlag  Word— Flag  controlling  disposition  of  last  error  field  for  record 

teHandle     -  Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 

<— SP 

Stack  after  call 


Previous  contents 


lastError 


Word— Last  error  code  generated  for  the  record 
<— SP 

Errors  $2202      teNotstarted  TextEdit  has  not  been  started 

C  extern  pascal  Word  TEGetLastError (clearFlag, 

teHandle) ; 

Word  clearFlag; 
Long  teHandle; 

clearFlag  Controls  what  TextEdit  does  with  the  last  error  field  after  servicing  the 

call: 

$0000  Leaves  the  last  error  code  intact 

$FFFF  Clears  the  last  error  code  to  $0000 
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TEGetRuler  $2322 

Returns  the  ruler  definition  for  a  TextEdit  record.  Your  program  specifies  the  destination 
for  the  ruler  information  and  the  TERecord  corresponding  to  the  appropriate  record. 
TEGetRuler  retums  the  TERuier  record  defining  the  ruler  for  the  record  in  question. 

Parameters 

Stack  before  call 


Previous  contents 


rulerDescriptor 


rulerRef 


teHandle 


Stack  after  call 


Word— Defines  type  of  reference  in  rulerRef 

Long— Reference  to  buffer  to  receive  TERuier  record 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


Errors 
C 


$2202 


<— SP 
teNotStarted 


TextEdit  has  not  been  started 


extern  pascal  void  TEGetRuler (rulerDescriptor, 
rulerRef,  teHandle) ; 

Word  rulerDescriptor; 
Long  rulerRef,  teHandle; 
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rulerDescriptor 

ref IsPointer 
ref IsHandle 
ref IsResource 
ref IsNewHandle 


Defines  the  type  of  reference  stored  in  rulerRef. 


teHandle 


$0000       rulerRef  conuins  a  pointer  to  a  buffer  to  receive  the 
TERuier  structure 

$0001        rulerRef  contains  a  handle  to  a  buffer  to  receive  the 
TERuier  structure 

$0002       rulerRef  contains  a  resource  ID  which  can  be  used  to 
access  a  buffer  to  receive  the  TERuier  structure 

$0003        rulerRef  contains  a  pointer  to  a  four-byte  buffer  to 
receive  a  handle  to  the  TERuier  structure; 
TEGetRuier  allocates  the  new  handle  and  returns  it 
in  the  specified  buffer 

Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEGetSelection  $1C22 

Returns  information  defining  the  current  selection  for  a  TextEdit  record.  Your  program 
specifies  the  TERecord  for  the  record  in  question.  TEGetseiection  then  determines 
the  starting  and  ending  byte  offsets  for  the  current  selection,  and  returns  those  values  into 
locations  specified  by  your  program. 

Both  offset  values  are  stored  as  four-byte  long  values.  If  there  is  no  current  selection  for 
the  specified  record,  both  the  starting  and  ending  offsets  will  contain  the  current  caret 
position. 

Parameters 

Stack  before  call 

Previous  contents 

-  selectionStart  -  Long— Pointer  to  buffer  to  receive  starting  offset  value 

-  selectionEnd  -  Long— Pointer  to  buffer  to  receive  ending  offset  value 

teHandle     -  Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


$2202 


teNotStarted 


TextEdit  has  not  been  started 


C 


extern  pascal  void  TEGetSelection (selectionStart, 
selectionEnd,   teHandle) ; 


Pointer  selectionStart,  selectionEnd; 
Long  teHandle; 


teHandle 


Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEGetSelectionStyle  $1E22 

Returns  all  style  information  for  the  text  in  the  current  selection  in  a  TextEdit  record.  Your 
program  specifies  the  TERecord  for  the  record  in  question  and  the  addresses  of  buffers 
to  receive  the  style  data.  TEGetseiectionstyie  then  loads  the  main  output  buffer 
with  TEStyie  structures  describing  all  styles  affecting  text  in  the  current  selection.  The 
first  word  in  the  buffer  contains  a  counter  indicating  the  number  ofiEStyie  structures 
returned. 

TEGetSelectionStyle  also  builds  a  common  style  record,  which  contains  all  style 
elements  which  are  common  to  all  text  in  the  selection.  A  flag  word  directs  your  program 
to  the  relevant  portions  of  the  common  style  record,  which  is  also  inxEStyie  format. 

If  there  is  no  current  selection,  TEGetSelectionStyle  returns  the  null  style  record, 
which  defines  the  style  that  will  be  applied  to  any  text  inserted  at  the  current  caret 
position. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


-  commonStylePt  - 


-  styleHandle 


teHandle 


Stack  after  call 


Word— Space  for  result 

Long— Pointer  to  TEStyie  buffer  for  common  style  record 
Long— Handle  to  buffer  for  style  information 
Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


commonFlag 


Word— Bit  flag  describing  common  style  record  contents 
<— SP 


Errors 


$2202  teNotStarted 


TextEdit  has  not  been  started 
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C  extern  pascal  Word 

TEGetSelectionStyle (commonStylePtr, 
styleHandle,  teHandle) ; 

Pointer  commonStylePtr; 

Long  StyleHandle,  teHandle; 

commonStylePtr   Points  to  a  buffer  to  receive  a  formatted  TEStyie  structure 

containing  the  style  elements  that  are  common  to  all  text  in  the  current 
selection.  commonFlag  indicates  which  portions  of  this  TEStyie 
structure  contain  valid  data. 

StyleHandle         Handle  to  a  buffer  to  receive  the  style  information  for  the  current 
selection.  TEGetSeiectionstyie  returns  as  many  TEStyie 
structures  as  are  required  to  fully  specify  all  the  styles  in  the  selection. 
If  the  buffer  referenced  by  styleHandle  cannot  store  enough  TEStyie 
structures,  TEGetSeiectionstyie  automatically  resizes  the  handle 
memory. 

On  return  from  TEGetSeiectionstyie,  the  buffer  referenced  by 
StyleHandle  wiW  be  formatted  as  follows: 


$00 

count 

Word 

$02 

style 


:  Array  of  TEStyie  structures 


count  Indicates  the  number  of  TEStyie  structures  in  the  styles 

array. 

styles  Array  of  count  TEStyie  Structures. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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commonFlag 

Reserved 
fUseFont 


fUseSize 


fUseForeColor 


fUseBackColor 


fUseUserData 


fUseAttributes 


Indicates  which  portions  of  the  common  style  record  pointed  to  by 
commonStylePtr  are  relevant: 


bits  6-15 
bit  5 


bit  4 


bit  3 


bit  2 


bit  1 


bitO 


Will  be  set  to  0 

The  font  family  defined  by  the  font  id  field  of  the 
common  style  record  is  valid; 
1  -  Font  family  valid 

0  -  Font  family  not  valid 

The  font  size  defined  by  the  font  id  field  of  the 
common  style  record  is  valid; 

1  -  Font  size  valid 

0  -  Font  size  not  valid 

The  fore  Color  field  of  the  common  style  record  is 
valid; 

1  -  f  oreColor  valid 

0  -  f  oreColor  not  valid 

The  backcoior  field  of  the  common  style  record  is 
valid; 

1  -backColor  valid 

0  -  backColor  not  valid 

The  userData  field  of  the  common  style  record  is 
valid; 

1  -  userData  valid 

0- userData  not  valid 

The  attributes  defined  by  the  font  id  field  of  the 
common  style  record  is  valid; 
1  -  Font  attributes  valid 
0  -  Font  attributes  not  valid 
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TEGetText  $0C22 

Returns  the  text  from  a  TextEdit  record,  including  the  style  information  associated  with 
that  text.  Your  program  specifies  the  TERecord  for  the  record  in  question,  the  format 
for  the  returned  text,  and  buffers  to  receive  the  text  and  style  data.  TEGetText  places 
the  text  in  the  return  buffer  in  the  format  requested  by  your  program;  style  information  is 
returned  in  a  TEFormat  structure. 

In  addition,  TEGetText  returns  a  value  indicating  the  total  length  of  the  text  in  the 
TextEdit  record.  This  value  represents  the  number  of  bytes  of  text  in  the  record,  not  the 
number  of  bytes  loaded  into  the  return  buffer.  If  the  retum  buffer  is  too  small  to  receive 
all  the  record  text,  TEGetText  returns  a  teBuf  f  erOverf  low  error.  This  error  is  also 
returned  if  the  text  is  too  large  to  be  returned  in  the  specified  format  (for  example,  the 
record  contains  300  text  characters  and  your  program  requested  an  output  Pascal  string). 

Parameters 

Stack  before  call 


Previous  contents 


Space 


bufferDescriptor 


bufferRef  - 


bufferLength  - 


styleDescriptor 


styleRef 


teHandle 


Long— Space  for  result 

Word— Defines  the  format  for  text  returned  at  bufferRef 
Long— Reference  to  the  output  text  buffer 

Long— Length  of  the  buffer  referred  to  by  bufferRef 

Word— Defines  the  type  of  reference  stored  in  styleRef 

Long— Reference  to  buffer  for  TEFormat  structure  defining  style 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


textLength 


Long— Total  length  of  all  text  in  record 
<— SP 
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Errors 


bufferDescriptor 
Reserved 

refFormat 


$2202  teNotStarted 
$2203  telnvalidHandle 

$2204  telnvalidDescriptor 
$2208  teBufferOverflow 

Memory  Manager  errors 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 
TERecord 

Invalid  descriptor  value  specified 
The  output  buffer  was  too  small 
to  accept  all  data 
Returned  unchanged 


extern  pascal  Long  TEGetText (bufferDescriptor, 
bufferRef,  buf f erLength,   styleDescriptor,  styleRef, 
teHandle) ; 

Long  bufferRef,  buf f erLength,  styleRef, 

teHandle; 

Word  bufferDescriptor,  styleDescriptor; 

Defines  the  format  in  which  TEGetText  should  return  the  record  text, 
and  the  type  of  reference  stored  in  bufferRef. 

bits  5-16    Must  be  set  to  0 

bits  3-4     Defines  the  type  of  reference  stored  in  bufferRef 

00  -  bufferRef  \s  a  pointer  to  the  output  buffer; 
bufferLength  contains  the  length  of  the  buffer  (in 
bytes) 

01  -  bufferRef  \s  a  handle  to  the  output  buffer; 
bufferLength  is  ignored 

10  -  bufferRef  \s,  a  resource  ID  for  the  output  buffer 
(TextEdit  will  create  the  resource  if  it  does  not 
already  exist);  bufferLength  is  ignored 

11  -  bufferRef  \s>  a  pointer  to  a  four-byte  buffer  to 
receive  a  handle  to  the  output  text;  TEGetText 
allocates  the  handle;  bufferLength  is  ignored 
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dataFormat  bits  0-2     Defines  the  format  for  the  output  text: 

000  -  Output  data  will  be  fonnatted  as  a  Pascal  string 
(resource  type  of  rPString) 

001  -  Output  data  will  be  formatted  as  a  C  string 
(resource  type  of  rcstring) 

010  -  Output  data  will  be  formatted  as  a  Class  1 
GS/OS  input  string  (resource  type  of 

rCl Input St ring) 

011  -  Output  data  will  be  formatted  as  a  Class  1 
GS/OS  output  string  (resource  type  of 
rcioutputstring);  application  need  not  set  the 
buffer  size  field 

100  -  Output  data  will  be  formatted  for  input  to 
LineEdit  TextBox2  tool  call  (resource  type  of 
rTextBox2)— see  Chapter  10,  "LineEdit  Tool  Set," 
in  the  Toolbox  Reference  for  details 

101  -  Output  data  will  be  returned  as  an  unformatted 
text  block  (resource  type  of  rxext) 

110  -  Invalid 

111  -  Invalid 


bufferLength  Defines  the  length  of  the  output  buffer  referenced  by  bufferRef,  if 
ref  Format  indicates  that  bufferRef  con^ms  a  pointer.  For  other 
types  of  references,  this  field  is  ignored. 


styleDescriptor 

Defines  the  type  of  reference  stored  in  styleRef 

ref IsPointer 

$0000 

StyleRef  comms  a  pointer  to  a  buffer  to  receive  the 
TE Format  Structure 

ref IsHandle 

$0001 

StyleRef  contains  a  handle  to  a  buffer  to  receive  the 
TEFormat  Structure 

ref IsResource 

$0002 

StyleRef  con\2dns  a  resource  ID  which  can  be  used  to 
access  a  buffer  to  receive  the  TEFormat  structure 

reflsNewHandle  $0003 

StyleRef  contains  a  pointer  to  a  four-byte  buffer  to 

receive  a  handle  to  the  TEFormat  structure; 

TEGetText  allocates  the  new  handle  and  returns  it  in 

the  specified  buffer 

StyleRef  Reference  to  buffer  to  receive  style  information,  in  TEFormat 

structure  form.  If  this  field  is  set  to  NULL,  then  TEGetText  will  not 
return  any  style  information,  and  will  ignore  styleDescriptor. 
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teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 

texlLength  Indicates  the  number  of  bytes  of  text  in  the  record.  Note  that  this 

value  may  exceed  the  number  of  bytes  returned  at  bufferRef,  if  the 
referenced  buffer  is  too  small  to  receive  all  the  text.  In  this  case, 
TEGetText  also  retums  a  teBuf  feroverf  low  error  code. 
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TEGetTextlnfo  $0D22 

Returns  a  variable-sized  information  record  describing  a  TextEdit  record.  Your  program 
specifies  the  TERecord  for  the  TextEdit  record  in  question,  the  address  of  a  buffer  to 
receive  the  information  record,  and  a  value  indicating  how  much  data  TEGetTextlnfo 
should  return.  The  system  returns  the  appropriate  data  at  the  specified  location. 

Parameters 

Stack  before  call 


Previous  contents 


-    infoRecPtr  - 


parameterCount 


teHandle 


Long— Pointer  to  buffer  for  information  record 

Word— Specifies  the  number  of  fields  to  return 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 

<— SP 


Stack  after  call 


Previous  contents 


Errors 


$2202 
$2203 

$2206 


<— SP 

teNotStarted 
telnvalidHandle 

telnvalidPCount 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 
TERecord 

Invalid  parameter  count  value 
specified 


extern  pascal  void  TEGetTextlnfo (infoRecPtr, 
parameterCount,  teHandle) ; 


Pointer 

Long 

Word 


infoRecPtr; 
teHandle; 
parameterCount ; 
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infoRecPtr  Points  to  a  buffer  to  receive  a  partial  or  complete  information  record, 

depending  upon  the  value  of  parameterComt.  The  information  record 
is  formatted  as  follows  (future  versions  of  TextEdit  may  add  fields  to 
the  end  of  this  record): 


$00 


$04 


$08 


$0C 


$10 


$14 


charCount         —  Long 


llneCount         -  Long 


f  ormatMemory       —  Long 


—       totalMemory       -  Long 


styleCount        —  Long 


—        rulerCount         —  Long 


CharCount        Contains  the  number  of  text  characters  in  the  record. 

linecount        Contains  the  number  of  lines  in  the  record.  A  line  is  defined  as  all 
text  that  is  displayed  on  a  single  line  of  the  screen,  based  upon 
the  current  display  options. 

f  ormatMemory    The  amount  of  memory  (in  bytes)  required  to  store  the  style 
information  for  the  record. 


totalMemory 

StyleCount 
rulerCount 


The  amount  of  memory  (in  bytes)  required  for  the  record, 
including  both  text  and  style  data. 

The  number  of  unique  styles  defined  for  the  record. 

The  number  of  rulers  defined  for  the  record. 
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parameterCount    Specifies  the  number  of  information  record  fields  to  be  returned  by 
TEGetTextinf  o.  Valid  values  lie  in  the  range  from  1  to  6.  Values 
outside  this  range  yield  a  teinvaiidPCount  error  code.  The 
returned  data  always  begin  with  the  charCount  field,  and  continue 
until  the  specified  number  of  fields  have  been  formatted. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEIdle  $0E22 

Provides  processor  time  to  TextEdit  so  that  it  can  blink  the  cursor  and  perform 
background  tasks.  Your  program  specifies  the  TERecord  for  the  record.  TextEdit  then 
determines  whether  enough  time  has  elapsed  to  require  a  cursor  blink,  and,  if  so,  blinks 
the  cursor.  In  addition,  TextEdit  performs  any  necessary  background  processing  for  the 
record. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Your  program  should  call  TEidie  often— usually  every  time  through  the  main  event  loop, 
and  periodically  during  time-consuming  operations.  If  your  program  does  not  call  TEidie 
often  enough,  the  cursor  will  blink  irregulariy.  TextEdit  ensures  that  the  cursor  blink  rate 
does  not  exceed  that  specified  by  the  user's  control  panel  setting. 

Parameters 

Stack  before  call 

Previous  contents 


teHandle 


Long— Handle  of  TERecord  in  memory 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


$2202 


teNotStarted 


TextEdit  has  not  been  started 


C 


extern  pascal  void  TEIdle (teHandle) ; 


Long 


teHandle; 
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TEInsert  $1A22 

Inserts  a  block  of  text  before  the  current  selection  in  a  TextEdit  record,  and  then  redraws 
the  text  screen.  Your  program  specifies  the  text  and  style  data  to  be  inserted  and  the 
TERecord  for  the  record.  TEinsert  then  inserts  the  text  and  style  data  at  the  current 
selection. 

This  call  does  not  affect  the  desk  scrap. 

Parameters 

Stack  before  call 


Previous  contents 


textDescriptor 


textRef 


textLength 


styleDescriptor 


styleRef 


teHandle 


Word— Defines  the  format  for  text  stored  at  textRef 
Long— Reference  to  the  input  text  buffer 
Long— Length  of  the  buffer  referred  to  by  textRef 
Word— Defines  the  type  of  reference  stored  in  styleRef 
Long— Reference  to  TEFormat  structure  defining  style  for  text 
Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$2202 
$220C 


<— SP 

teNotStarted 
teInvalidTextBox2 


Memory  Manager  errors 


TextEdit  has  not  been  started 
The  TextBox2  format  codes 
were  inconsistent 
Returned  unchanged 


extern  pascal  void  TEInsert (textDescriptor,  textRef, 
textLength,   styleDescriptor,  styleRef, 
teHandle) ; 

Long  textRef,  textLength,   styleRef,  teHandle; 

Word  textDescriptor,  styleDescriptor; 
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texlDescriptor       Defines  the  format  of  the  text  to  be  inserted,  and  the  type  of 
reference  stored  in  texlRef. 

Reserved  bits  5-16    Must  be  set  to  0 

refFormat  bits  3-4     Defines  the  type  of  reference  stored  in  textRef. 

00  -  textRef  iS  a  pointer  to  the  text  buffer;  text  Length 
contains  the  length  of  the  buffer  (in  bytes) 

01  -  textRef  is  a  handle  to  the  text  buffer;  textLength  is 
ignored 

10  -  textRef  \s  a  resource  ID  for  the  text  buffer; 
textLength  is  ignored 

11  -  Invalid 

dataFormat  bits  0-2     Defines  the  format  of  the  text: 

000  -  Text  is  a  Pascal  string  (resource  type  of 
rPString) 

001  -  Text  is  a  C  string  (resource  type  of  rest  ring) 

010  -  Text  is  a  Class  1  GS/OS  input  string  (resource 
type  of  rCl  Input  St  ring) 

011  -  Text  is  a  Class  1  GS/OS  output  string  (resource 

type  of  rClOutputString) 

100  -  Text  is  formatted  for  input  to  LineEdit 
TextBox2  tool  call  (resource  type  of 
rTextBox2>— see  Chapter  10,  "LineEdit  Tool  Set," 
in  the  Toolbox  Reference  for  details;  style  data  in  the 
text  overrides  that  specified  by  styleRef 

101  -  Text  is  an  unformatted  text  block  (resource 
type  of  next) 

110  -  Invalid 

111  -  Invalid 

textLength  Defines  the  length  of  the  buffer  referenced  by  textRef  This  field  is  only 

valid  for  reference  types  that  do  not  contain  length  data  (see 
texlDescriptor).  For  other  types  of  references,  this  field  is  ignored. 

styleDescriptor      Defines  the  type  of  reference  stored  in  styleRef 

refisPointer        $0000        5/jv/e/?e/contains  a  pointer  to  a  TEFormat  Structure 
ref  isHandie         $0001        5/ye7?e/ contains  a  handle  to  a  TEFormat  structure 
ref  I sResource       $0002       StyleRef  comins  a  resource  ID  which  can  be  used  to 

access  a  buffer  containing  the  TEFormat  structure 
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styleRef  Reference  to  buffer  containing  style  information,  in  TEFormat 

structure  form.  If  this  field  is  set  to  NULL,  then  TEinsert  will  use  the 
style  of  the  first  character  in  the  current  selection  for  the  record,  and 
wiO  ignore  styleDescriptor. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEKey  $1422 

Processes  a  keystroke  for  a  TextEdit  record.  Your  program  specifies  the  TERecord  for 
the  record  and  the  event  record  for  the  keystroke.  TEKey  then  processes  the  key.  If  the 
keystroke  is  a  control  key  (one  that  requires  special  processing,  as  outlined  in  "Standard 
TextEdit  key  sequences"  earlier  in  this  chapter),  TEKey  performs  the  appropriate 
TextEdit  action.  If  the  keystroke  is  not  a  control  key,  TEKey  inserts  the  corresponding 
character  into  the  text  of  the  target  TextEdit  record  at  the  current  selection. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Your  program  should  issue  this  call  in  response  to  KeyOown  or  AutoKey  events. 

Parameters 

Stack  before  call 


Previous  contents 


-  eventRecordPtr 


teHandle 


Long— Pointer  to  event  record  for  the  key 
Long— Handle  of  TERecord  in  memory 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

$2202  teNotStarted 
Memory  Manager  errors 


TextEdit  has  not  been  started 
Returned  unchanged 


extern  pascal  void  TEKey (eventRecordPtr,  teHandle) 


eventRecordPtr 


Pointer  eventRecordPtr; 
Long  teHandle; 

Points  to  the  event  record  describing  the  keystroke.  For  information 
on  the  format  and  content  of  event  records,  see 
Chapter  7,  "Event  Manager,"  in  the  Toolbox  Reference 
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TEKill  $0A22 

Deallocates  a  TERecord  and  all  associated  memory.  Your  program  specifies  the 
TERecord  to  be  freed.  tekIii  then  releases  the  record  and  any  memory  supporting  it. 
TEKill  does  not  erase  or  invalidate  the  screen,  nor  does  it  make  another  record  the 
target  if  the  target  record  is  killed.  Your  program  must  take  care  of  these  duties. 

Your  program  should  issue  this  call  only  when  it  is  completely  through  with  the  TERecord 
and  its  TextEdit  record— all  text  associated  with  the  record  is  lost  after  this  call. 

If  your  program  uses  TextEdit  controls  it  may  issue  the  Kiiicontrois  or 
DisposeControi  Control  Manager  tool  calls  instead  of  tekiii. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long— Handle  of  TERecord  in  memory 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$2202 
$2203 


<— SP 

teNotStarted 
telnvalidHandle 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 
TERecord 


extern  pascal  void  TEKill (teHandle) ; 
Long  teHandle; 
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TENew  $0922 

Allocates  a  new  TextEdit  record  in  the  current  port,  and  returns  the  TERecord  defining 
that  record.  Your  program  specifies  the  parameters  for  that  record  in  a  TEParamBiock 
structure  (see  "TextEdit  data  structures"  earlier  in  this  chapter  for  information  on  the 
format  and  content  of  the  TEParamBiock).  TextEdit  then  allocates  and  formats  the 
TERecord  for  the  record. 

The  bounds  rectangle  specified  in  the  TEParamBiock  must  be  large  enough  to 
completely  enclose  a  single  character  in  the  largest  allowable  font  for  the  record. 

Your  program  should  issue  this  call  only  if  it  is  not  using  TextEdit  controls.  In  order  to 
create  a  TextEdit  control,  use  the  NewControi2  Control  Manager  tool  call  (see 
Chapter  28,  "Control  Manager  Update,"  in  this  book).  Note  that  NewControi2  may  be 
used  to  create  several  controls  at  once. 

Parameters 

Stack  before  call 


Prmous  contents 


Space 


-  parameterBlock  - 


Long— Space  for  result 

Long — Pointer  to  formatted  TEParamBiock 
<— SP 


Stack  after  call 


Previous  contents 


teHandle 


Errors 


$2202 
$2204 
$2205 


Long— Handle  to  new  TERecord 
<— SP 


teNotstarted  TextEdit  has  not  been  started 

teinvaiidDescriptor  Invalid  descriptor  value  specified 

textFlagsi\t\d  of  TEParamBiock 
is  invalid 

Invalid  parameter  count  value 
specified 

Returned  unchanged 


telnvalidFlag 
$2206  telnvalidPCount 
Memory  Manager  errors 
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extern  pascal  Long  TENew (parameterBlock) ; 
Pointer  parameterBlock; 
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TEOf fsetToPoint  $2022 

Converts  a  text  byte  offset  into  a  pixel  position  expressed  in  the  local  coordinates  of  the 
GrafPort  containing  the  TextEdit  record.  Your  program  specifies  the  byte  offset  to  the 
character  in  question,  the  addresses  of  buffers  to  receive  the  pixel  position  information, 
and  the  TERecord  for  the  record,  TEOf  fsetToPoint  then  determines  the  pixel 
position  for  the  character. 

The  returned  pixel  position  is  expressed  as  two  signed  long  integers.  If  the  specified 
offset  is  beyond  the  end  of  the  text  for  the  record,  TEOf  fsetToPoint  returns  the 
position  of  the  last  character.  Note  that  if  the  specified  character  lies  above  the  display 
rectangle,  the  vertical  position  component  will  be  a  negative  value.  The  pixel  position  is 
not  expressed  as  a  QuickDraw  II  point,  because  the  TextEdit  drawing  space  is  larger  than 
the  QuickDraw  II  drawing  space. 

The  TEPointToOf  f  set  call  performs  the  inverse  operation,  converting  a  pixel  position 
into  a  text  offset. 

Parameters 

Stack  before  call 


Previous  contents 


textOffset 


vertPosPtr 


-    horzPosPtr  - 


teHandle 


Stack  after  call 


Long— Byte  offset  to  text 

Long— Pointer  to  four-byte  buffer  to  receive  vertical  position 

Long— Pointer  to  four-byte  buffer  to  receive  horizontal  position 

Long — Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


Errors 


<— SP 

$2202  teNotStarted 


TextEdit  has  not  been  started 


49-106  Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


C  extern  pascal  void  TEOf f setToPoint (textOf f set, 

vertPosPtr,   horzPosPtr,   teHandle) ; 

Long  textOffset,  teHandle; 

Pointer      vertPosPtr,  horzPosPtr; 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEPaintText  $1322 

Prints  the  text  from  a  TextEdit  record.  Your  program  specifies  the  destination  rectangle 
and  GrafPort,  print  control  information,  and  the  TextEdit  record  from  which 
TEPaintText  is  to  print.  TextEdit  then  draws  the  appropriate  record  text  into  the 
specified  rectangle  and  GrafPort.  TEPaintText  begins  printing  at  a  line  number  you 
specify,  and  continues  until  the  destination  rectangle  has  been  filled.  The  routine  then 
returns  the  next  line  number  to  be  printed  so  that  your  program  can  issue  the  next  call 
correctly. 

Your  program  issues  this  tool  call  within  a  Print  Manager  job,  which  you  start  by  calling 
PrOpenDoc.  The  Print  Manager  returns  the  GrafPort  pointer  when  you  initiate  the  job. 
Refer  to  Chapter  15,  "Print  Manager,"  of  the  Toolbox  Reference  for  complete  information 
on  starting,  managing,  and  ending  a  print  job. 

Note  that  this  call  is  not  limited  to  printing;  your  application  can  use  this  tool  call  to  paint 
into  any  GrafPort. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


graJPort 


-    startingLine  - 


rectPtr 


flags 


teHandle 


Stack  after  call 


Long — Space  for  result 

Long — Pointer  to  destination  GrafPort 

Long— Starting  line  number  for  print  operation 

Long— pointer  to  the  destination  rectangle  in  GrafPort 
Word — Control  flags  for  the  print  operation 
Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


nextLine 


Long— Next  line  number  to  print 
<— SP 
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Errors  $2202      teNotstarted  TextEdit  has  not  been  started 

$2209      teinvaiidLine  Starting  line  value  is  greater  than 

the  number  of  lines  in  the  text 
(end-of-file) 

C  extern  pascal  Long  TEPaintText (graf Port, 

startingLine,   rectPtr,   flags,  teHandle) ; 


Pointer 

Long 

Word 

StartingLine 
grafPort 

rectPtr 


flags 

fPartialLines  bit  15 
fDontDraw  bit  14 


grafPort,  rectPtr; 
StartingLine,  teHandle; 
flags; 
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Specifies  the  first  line  to  be  printed,  A  line  is  defined  as  all  text  that  is 
displayed  on  a  single  line  of  the  screen,  based  upon  the  current  display 
options. 

Points  to  a  QuickDraw  II  GrafPort  definition  which  describes  the 
destination  for  the  print  operation.  For  more  information  on  the 
format,  content,  and  use  of  the  GrafPort  structure,  see 
Chapter  l6,  "QuickDraw  II,"  in  the  Toolbox  Reference. 

Points  to  a  structure  defining  the  destination  rectangle  for  the  print 
operation.  This  rectangle  essentially  defines  the  output  page  size,  and 
must  lie  in  the  output  GrafPort  specified  by  grafPort.  Each  print 
operation  initiated  by  TEPaintText  ends  when  the  rectangle 
described  by  the  structure  pointed  to  by  rectPtr  fills.  Refer  to  the 
description  of  the  PrOpenPage  tool  call  in 
Chapter  15,  "Print  Manager,"  of  the  Toolbox  Reference  for  more 
information  on  this  frame  rectangle. 

Controls  the  print  operation: 


Reserved;  must  be  set  to  0 
Controls  printing: 

0  -  Print  data 

1  -  Calculate  the  number  of  lines  that  will  fit  in  rectPtr, 
but  do  not  pmi—nextLine  still  contains  next  line  to 
print  just  as  if  text  had  been  printed  (supports  page 
skip) 

Reserved  bits  0-13    Must  be  set  to  0 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEPaste  $1822 

Replaces  the  current  selection  with  the  contents  of  the  desk  scrap,  including  both  text 
and  style  information.  Your  program  specifies  the  TERecord  for  the  TextEdit  record  in 
which  the  operation  is  to  take  place.  TEPaste  then  pastes  the  data  from  the  desk  scrap 
into  the  record  text.  If  the  desk  scrap  is  empty,  the  current  selection  is  untouched. 

Your  application  need  issue  this  call  only  if  it  is  managing  its  own  TextEdit  records.  If  your 
program  uses  TextEdit  controls,  it  should  not  issue  this  call;  TaskMaster  manages  the 
control  automatically. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


<— SP 

$2202  teNotStarted 
Memory  Manager  errors 


TextEdit  has  not  been  started 
Returned  unchanged 


extern  pascal  void  TEPaste (teHandle) ; 


Long  teHandle; 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEPointToOf f set  $2122 

Converts  a  pixel  position  expressed  in  the  local  coordinates  of  the  GrafPort  containing 
the  TextEdit  record  into  a  text  byte  offset  into  the  text  for  the  record.  Your  program 
specifies  the  pixel  position  in  terms  of  its  relative  horizontal  and  vertical  location  in  the 
GrafPort,  but  not  as  a  QuickDraw  II  point.  TEPointToof  f  set  then  generates  the 
appropriate  text  offset  within  the  record. 

The  vertical  and  horizontal  components  of  the  pixel  position  are  represented  as  signed 
Long  integers.  If  the  specified  position  lies  before  the  first  text  character  in  the  record, 
then  the  returned  offset  will  be  $00000000.  If  the  position  is  after  the  last  text  character, 
the  call  returns  the  offset  of  the  last  character  in  the  record.  If  your  program  specifies  a 
horizontal  position  beyond  the  last  character  in  a  line,  TEPointToof  f  set  returns  the 
offset  of  the  last  character  in  the  line. 

The  TEOf  f  setToPoint  Call  performs  the  inverse  operation,  converting  a  text  offset 
into  a  pbcel  position. 

Parameters 

Stack  before  call 


Prmous  contents 


Space 


vertPos 


horzPos 


teHandle 


Long— Space  for  result 

Long— Vertical  position  component 

Long— Horizontal  position  component 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Stack  after  call 


Previous  contents 


textOffset 


Long— Byte  offset  to  text  corresponding  to  pixel  position 
<— SP 


Errors 


$2202  teNotStarted 


TextEdit  has  not  been  started 


Chapter  49  TextEdit  49-111 


Apple  lies  Toolbox  Reference,  Volume  5 


Beta  Draft 


30  August  1989 


C  extern  pascal  Long  TEPointToOf f set (vertPos,  horzPos, 

teHandle) ; 

Long  vertPos,  horzPos,  teHandle; 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEReplace  $1B22 

Replaces  the  current  selection  in  a  TextEdit  record  with  a  specified  block  of  text,  and 
then  redraws  the  text  screen.  Your  program  specifies  the  text  and  style  data  to  be 
inserted  and  the  TERecord  for  the  record.  TEReplace  then  inserts  the  text  and  style  data 
in  place  of  the  current  selection. 

This  call  does  not  affect  the  desk  scrap. 

Parameters 

Stack  before  call 


Previous  contents 


textDescriptor 


textRef 


textLength 


styleDescriptor 


styleRef 


teHandle 


Stack  after  call 


Word— Defines  the  format  for  text  stored  at  textRef 
Long— Reference  to  the  input  text  buffer 

Long— Length  of  the  buffer  referred  to  by  textRef 
Word— Defines  the  type  of  reference  stored  in  styleRef 
Long— Reference  to  TEFormat  structure  defining  style  for  text 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Pretnous  contents 


Errors 


$2202 
$220C 


<— SP 

teNotStarted 
teInvalidTextBox2 


Memory  Manager  errors 


TextEdit  has  not  been  started 
The  TextBcx2  format  codes 
were  inconsistent 
Returned  unchanged 


extern  pascal  void  TEReplace (textDescriptor, 

textRef,  textLength,  styleDescriptor, 
StyleRef,  teHandle) ; 

Long  textRef,  textLength,   styleRef,  teHandle; 

Word  textDescriptor,  styleDescriptor; 
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textDescriptor      Defines  the  format  of  the  text  to  be  inserted,  and  the  type  of 
reference  stored  in  textRef. 

Reserved  bits  5-16    Must  be  set  to  0 

ref  Format  bits  3-4     Defines  the  type  of  reference  stored  in  textRef. 

00  -  textRef is  a  pointer  to  the  text  buffer;  textLength 
contains  the  length  of  the  buffer  (in  bytes) 

01  -  textRef  is  a  handle  to  the  text  buffer;  textLength  is 
ignored 

10  -  textRef  is  a  resource  ID  for  the  text  buffer; 
textLength  is  ignored 

11  -  Invalid 

dataFormat  bits  0-2     Defines  the  format  of  the  text: 

000  -  Text  is  a  Pascal  string  (resource  type  of 

rPString) 

001  -  Text  is  a  C  string  (resource  type  of  rest  ring) 

010  -  Text  is  a  Class  1  GS/OS  input  string  (resource 
type  of  rCl  Input  St  ring) 

011  -  Text  is  a  Class  1  GS/OS  output  string  (resource 

type  of  rClOutputString) 

100  -  Text  is  formatted  for  input  to  LineEdit 
TextBox2  tool  call  (resource  type  of  rTextBox2)— 
see  Chapter  10,  "LineEdit  Tool  Set,"  in  the  Toolbox 
Reference  for  details;  style  data  in  the  text  overrides 
that  specified  by  styleRef 

101  -  Text  is  an  unformatted  text  block  (resource 
type  of  rText) 

110  -  Invalid 

111  -  Invalid 

textLength  Defines  the  length  of  the  buffer  referenced  by  textRef  This  field  is  only 

valid  for  reference  types  that  do  not  contain  length  data  (see 
textDescriptor).  For  other  types  of  references,  this  field  is  ignored. 

styleDescriptor      Defines  the  type  of  reference  stored  in  styleRef 


reflsPointer  $0000 
reflsHandle  $0001 
ref IsResource  $0002 


StyleRef  con\2i\ns,  a  pointer  to  a  TEPormat  structure 
StyleRef  con\2.\r\s  a  handle  to  a  TEFormat  structure 
StyleRef  contains  a  resource  ID  which  can  be  used  to 
access  a  buffer  containing  the  TEFormat  structure 
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styleRef  Reference  to  buffer  containing  style  information,  in  TEFormat 

structure  form.  If  tliis  field  is  set  to  NULL,  then  TEinsert  will  use  the 
first  defined  style  in  the  current  selection  for  the  record,  and  will 
ignore  styleDescriptor. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEScroll  $2522 

Scrolls  the  text  in  a  TextEdit  record.  Your  program  specifies  control  information  for  the 
scroll  and  the  TERecord  for  the  record.  TEScroii  then  updates  the  current  position  for 
the  record  accordingly. 

Parameters 

Stack  before  call 


Prmous  contents 


scrollDescriptor 


vertAmount  - 


-  horzAmount  - 


teHandle 


Stack  after  call 


Word — Control  information  for  the  scroll  operation 
Long— Vertical  amount  to  scroll  (this  is  a  signed  value) 

Long— Horizontal  amount  to  scroll  (Must  be  set  to  0) 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Previous  contents 


Errors 
C 


$2202 


<— SP 
teNotStarted 


TextEdit  has  not  been  started 


extern  pascal  void  TEScroll (vertAmount,  horzAmount, 
teHandle) ; 


Long 


vertAmount,  horzAmount,  teHandle; 
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scrollDescriptor     Defines  the  nature  of  the  scroll  operation,  and  the  use  of  and  units  for 
vertAmount  and  horzAmount: 

$0000  Scroll  to  absolute  text  position,  place  at  top  of  window.  The 

vertAmount  parameter  contains  the  offset  value  for  the  text 
character  to  place  at  the  top  of  the  TextEdit  display  window. 
The  horzAmount  parameter  is  ignored. 

$0001  Scroll  to  absolute  text  position,  center  in  window.  The 

vertAmount  parameter  contains  the  offset  value  for  the  text 
character  to  place  in  the  center  of  the  TextEdit  display  window. 
The  horzAmount  parameter  is  ignored. 

$0002  Scroll  to  line,  place  at  top  of  window.  The  vertAmount  parameter 

contains  a  line  number  specifying  which  text  line  to  place  at  the 
top  of  the  TextEdit  display  window.  The  horzAmount 
parameter  is  ignored. 

$0003  Scroll  to  line,  center  in  window.  The  vertAmount  parameter 

contains  a  line  number  specifying  which  text  line  to  center  in  the 
TextEdit  display  window.  The  horzAmount  parameter  is 
ignored. 

$0004  Scroll  to  absolute  unit  position,  place  at  top  of  window.  The 

vertAmount  parameter  contains  a  value  to  which  to  scroll  the  top 
of  the  TextEdit  window,  in  units  defined  by  the  value  of  the 
vertScrollAmount  Md  of  the  TERecord  for  the  record.  The 
horzAmount  parameter  must  be  set  to  0. 

$0005  Scroll  to  relative  unit  position,  place  at  top  of  window.  The 

vertAmount  parameter  contains  a  value  to  add  to  contents  of 
the  vertScrollPosMd  of  the  TERecord  for  the  record,  in  units 
defined  by  the  value  of  the  vertScrollAmount  field  of  that 
TERecord.The  horzAmount  parameter  must  be  set  to  0. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TESetRuler  $2422 

Sets  the  mler  for  a  TextEdit  record.  Your  program  specifies  the  new  ruler  definition,  in 
TERuier  format,  and  the  TERecord  for  the  record.  TESetRuier  then  sets  the  mler  as 
specified,  and  reformats  all  text  in  the  record.  For  TextEdit  controls,  TESetRuier 
invalidates  the  entire  display  rectangle  (the  screen  will  be  redrawn  on  the  next  update 
event).  For  TextEdit  records  that  are  not  controls,  TESetRuier  redraws  the  screen. 

Parameters 

Stack  before  call 

Previous  contents 

rulerDescriptor  Word— Defines  type  of  reference  in  rulerRef 

nilerRef     -  Long— Reference  to  buffer  containing  new  TERuier  structure 

teHandle     -  Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 

Stack  after  call 


Previous  contents 


<— SP 

Errors  $2202      teNotstarted  TextEdit  has  not  been  started 

C  extern  pascal  void  TESetRuier (rulerDescriptor, 

rulerRef,  teHandle) ; 

Word  rulerDescriptor; 
Long  rulerRef,  teHandle; 

rulerDescriptor     Defines  the  type  of  reference  stored  in  rulerRef. 

refisPointer        $0000        rM/er/?e/contains  a  pointer  to  a  buffer  containing  the 

TERuier  structure 

ref  isHandie         $0001        rulerRef  contains  a  handle  to  a  buffer  containing  the 

TERuier  structure 

ref  I  sResource       $0002       rulerRef  contains  a  resource  ID  which  can  be  used  to 

access  a  buffer  containing  the  TERuier  structure 
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teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TESetSelection  $1D22 

Sets  the  current  selection  for  a  TextEdit  record.  Your  program  specifies  the  starting  and 
ending  text  byte  offsets  for  the  selection  and  die  TERecord  for  the  record. 
TESetSelection  then  updates  the  record  accordingly. 

If  the  ending  offset  value  is  less  than  the  starting  value,  TESetSelection  automatically 
swaps  them.  If  eidier  offset  is  beyond  the  end  of  the  text  for  the  record,  it  is  reset  to  the 
offset  for  the  last  character. 

Parameters 

Stack  before  call 

Previous  contents 

-  selectionStart  -  Long— Starting  offset  value 

-  selectionEnd  -  Long— Ending  offset  value 

teHandle     -  Long — Handleof  TERecord  in  memory;  NULL  for  active  record 


<— SP 


Stack  after  call 


Previous  contents 


<— SP 


Errors 


$2202 
$2203 


telnvalidHandle 


teNotStarted 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 
TERecord 


C 


extern  pascal  void  TESetSelection (selectionStart, 
selectionEnd,  teHandle) ; 


teHandle 


Pointer      selectionStart,  selectionEnd; 
Long  teHandle; 

Specifies  the  TextEdit  record  for  the  operation.  If  your  program 
specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 


49-120  Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


TESetText  $0B22 

Replaces  the  text  in  a  TextEdit  record,  including  style  information,  with  supplied  text  and 
style  data.  Your  program  supplies  the  text  and  style  information,  along  with  the 
TERecord  for  the  TextEdit  record.  TESetText  then  replaces  any  existing  text  and  style 
information  in  the  record  with  the  supplied  data.  For  TextEdit  controls,  TESetText  then 
invalidates  die  entire  display  rectangle  (the  screen  will  be  redrawn  on  the  next  update 
event).  For  TextEdit  records  that  are  not  controls,  TESetText  redraws  the  screen 
immediately. 

Supplied  style  information  must  be  formatted  in  a  TEFormat  structure. 

Parameters 

Stack  before  call 


Previous  contents 


textDescriptor 


textRef 


textLength 


styleDescriptor 


styleRef 


teHandle 


Stack  after  call 


Word— Defines  the  format  for  text  stored  at  textRef 
Long— Reference  to  the  input  text 

Long— Length  of  the  buffer  referred  to  by  textRef 
Word— Defines  the  type  of  reference  stored  in  styleRef 
Long— Reference  to  TEFormat  structure  defining  style 

Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 


Premous  contents 


Errors 


<— SP 


$2202  teNotStarted 
$2203  telnvalidHandle 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 


TERecord 

$2204  teinvaiidDescriptor  Invalid  descriptor  value  specified 
Memory  Manager  errors  Returned  unchanged 
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C  extern  pascal  void  TESetText (textDescriptor, 

textRef,   textLength,  styleDescriptor, 
styleRef ,  teHandle) ; 

Long  textRef,  textLength,   styleRef,  teHandle; 

Word  textDescriptor,  styleDescriptor; 

textDescriptor       Defines  the  format  of  the  new  text  for  the  record,  and  the  type  of 
reference  stored  in  textRef. 

Reserved  bits  5-16    Must  be  set  to  0 

refFormat  bits  3-4     Defines  the  type  of  reference  stored  in  textRef. 

00  -  textRef'^  a  pointer  to  the  text;  textLength 
contains  the  length  of  the  buffer  (in  bytes) 

01  -  textRef  is  a  handle  to  the  text;  textLength  is 
ignored 

10  -  textRef  \s  a  resource  ID  for  the  text;  textLength  is 
ignored 

11  -  Invalid  value 

dataFormat  bits  0-2     Defines  the  format  of  the  text; 

000  -  Text  is  a  Pascal  string  (resource  type  of 
rPString) 

001  -  Text  is  a  C  string  (resource  type  of  rcstring) 

010  -  Text  is  a  Class  1  GS/OS  input  string  (resource 
type  of  rClInputString) 

011  -  Text  is  a  Class  1  GS/OS  output  string  (resource 
type  of  rCl  Output  St  ring) 

100  -  Text  is  formatted  for  input  to  LineEdit 
TextBox2  tool  call  (resource  type  of 
rTextBox2)— see  Chapter  10,  "LineEdit  Tool  Set," 
in  the  Toolbox  Reference  for  details;  style  data  in  the 
text  overrides  that  specified  by  styleRef 

101  -  Text  is  an  unformatted  text  block  (resource 
type  of  rText) 

110  -  Invalid 

111  -  Invalid 

textLength  Defines  the  length  of  the  output  buffer  referenced  by  textRef  This 

field  is  only  valid  for  reference  types  that  do  not  contain  length  data 
(see  textDescriptor).  For  other  types  of  references,  this  field  is  ignored. 
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styleDescriptor      Defines  the  type  of  reference  stored  in  styleRef. 

ref  isPointer        $0000       StyleRef  contzins  a  pointer  to  the  TEFormat  structure 
ref  isHandie         $0001       StyleRef  contnins  a  handle  to  the  TEFormat  structure 
ref  isResource      $0002       StyleRef  contains  a  resource  E)  which  can  be  used  to 

access  the  TEFormat  structure 

StyleRef  Reference  to  style  information  for  the  new  text,  in  TEFormat 

structure  form.  If  this  field  is  set  to  NULL,  then  TESetText  uses  the 
first  style  encountered  in  the  existing  text  for  the  record. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 
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TEStyleChange  $1F22 

Changes  the  style  information  for  the  current  selection  in  a  TextEdit  record.  Your 
program  specifies  the  style  information  and  the  TERecord  for  the  record.  TEStyleChange 
then  applies  that  new  information  to  all  the  styles  in  the  current  selection.  If  there  is  no 
current  selection,  then  the  new  style  applies  to  the  null  style  record,  which  defines  style 
information  for  newly  inserted  text. 

Parameters 

Stack  before  call 

Previous  contents 

flags  Word— Control  flag  for  applying  style  data  from  TEStyie 
stylePtr      -  Long— Pointer  to  TEStyie  structure 

teHandle     -  Long— Handle  of  TERecord  in  memory;  NULL  for  active  record 
<— SP 

Stack  after  call 


Previous  contents 


Errors 


$2202 
$2205 


<— SP 

teNotStarted 
telnvalidFlag 


TextEdit  has  not  been  started 
Specified  flag  word  is  invalid 


extern  pascal  void  TEStyleChange (flags,  stylePtr, 
teHandle) ; 


Word 

Pointer 

Long 


flags; 

StylePtr; 

teHandle; 
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flags 
Reserved 

f ReplaceFont 


f ReplaceSize 


Indicates  which  portions  of  the  TEStyie  stnicture  pointed  to  by 
stylePtrzxt  relevant: 

bits7-15     Must  be  set  to  0 

bit  6         Controls  use  of  font  family  defined  by  font  id  field 
of  TEStyie  structure: 

1  -  Replace  the  font  faniily  for  all  styles  in  the  current 
selection 

0  -  Do  not  change  font  family 

bit  5         Controls  use  of  font  size  defined  by  font  id  field  of 
TEStyie  structure 

1  -  Replace  the  font  size  for  all  styles  in  the  current 
selection 

0  -  Do  not  change  font  size 


f ReplaceForeColor 


bit  4 


fReplaceBackColor 


bit  3 


fReplaceUserData  bit  2 


fReplaceAttributes 

bit  1 


Controls  use  of  foreColor  field  of  TEStyle 

structure: 

1  -  Replace  the  foreground  color  for  all  styles  in  the 
current  selection 

0  -  Do  not  change  the  foreground  color 

Controls  use  of  backColor'field  of  TEStyle 
structure: 

1  -  Replace  the  background  color  for  all  styles  in  the 
current  selection 

0  -  Do  not  change  the  background  color 
Controls  the  use  of  the  userData  field  of  the 
TEStyle  structure: 

1  -  Replace  the  userData  field  for  all  styles  in  the 
current  selection  with  that  in  the  supplied  XEStyie 
structure 

0  -  Do  not  change  userData  field 

Controls  use  of  font  attributes  defined  by  the 
fontiD  field  of  TEStyle  Structure: 

1  -  Replace  the  font  attributes  for  all  styles  in  the 
current  selection 

0  -  Do  not  change  font  attributes 


Chapter  49  TextEdit  49-125 


Apple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


f SwitchAttributes 

bit  0         Controls  attribute  switching; 

1  -  If  the  entire  selection  contains  the  font  attributes 
specified  by  the  TEStyie  structure  font  id  field, 
then  these  attributes  are  removed  from  the  selection; 
otherwise,  the  specified  attributes  are  added  to 
those  already  defined  for  the  selection  (note  that  the 
attributes  are  considered  together,  not  individually) 
0  -  Perform  no  attribute  switching 

♦  Note:  The  f  ReplaceAttributes  and  f  SwitchAttributes  flags  are  mutually 
exclusive.  If  both  flags  are  set  to  1,  TEStyieChange  returns  a  teinvaiidFiag 
error  code. 


stylePtr  Points  to  a  formatted  te  style  structure  containing  the  style 

elements  that  are  to  be  applied  to  the  current  selection.  The  flags 
parameter  indicates  which  portions  of  this  TEStyie  structure 
contain  valid  data. 

teHandle  Specifies  the  TextEdit  record  for  the  operation.  If  your  program 

specifies  a  NULL  value,  TextEdit  works  with  the  target  TextEdit 
record.  If  there  is  no  target  record,  then  TextEdit  does  nothing  and 
returns  immediately  to  your  program. 


49-126  Apple  ncs  Toolbox  Reference,  Volume  3 


Apple IIGS  Toolbox  Reference,  Volumes 


Beta  Draft 


30  August  1989 


TEUpdate  $1222 

Redraws  the  screen  for  a  TextEdit  record.  Your  program  specifies  the  TERecord  for  the 
record.  TEUpdate  then  redraws  the  text  for  the  record.  Only  that  portion  of  the  screen 
that  must  be  redrawn  is  affected. 

Your  program  should  issue  this  call  after  the  Window  Manager  Beginupdate  call,  and 
before  an  Endupdate  call.  Issue  this  call  separately  for  each  TextEdit  record  in  the 
window.  TextEdit  returns  very  quickly  if  no  redraw  is  required. 

If  your  program  uses  TextEdit  controls,  use  the  ControlManager  DrawControis  tool  call, 
rather  than  this  one. 

Parameters 

Stack  before  call 


Previous  contents 


teHandle 


Long— Handle  of  TERecord  in  memory 
<— SP 


Stack  after  call 


Previous  contents 


Errors 


$2202 
$2203 


<— SP 

teNotStarted 
telnvalidHandle 


TextEdit  has  not  been  started 
teHandle  does  not  refer  to  a  valid 
TERecord 


extern  pascal  void  TEUpdate (teHandle) ; 
Long  teHandle; 
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TextEdit  summary 

This  section  summarizes  the  constants,  data  structures,  and  error  codes  used  by  the 
Resource  Manager. 


Table  49-1      TextEdit  constants 


Name 


Value 


Description 


Jiistification  values 

left Just 
rightJust 
centerJust 
fullJust 


$0000 
$FFFF 
$0001 
$0002 


TERuler  flags  field  values 

f Showlnvisibles  $2000 
fEqualLineSpacing  $4000 

TERuler  tabType  field  values 

noTabs  $0000 
stdTabs  $0001 


absTabs 


$0002 


TEParamBloclc  flags  field  values 


fCtllnvis 
fRecordDirty 


$0080 
$0040 


Left  justify  all  text 
Right  justify  all  text 
Center  all  text 

Fully  justify  all  text  (both  left  and  right 
margins) 


Show  invisible  characters  (space,  tab, 
return) 

TextEdit  uses  maximum  line  spacing 
for  every  line  in  the  block 


No  tabs  defined— tabType  is  last 

field  in  TERuler  structure 

Tabs  every  tabTerminator  pbcels — 

tabTerminator  is  last  field  in  the 

TERuler  Structure;  thelabs  is 

omitted 

Tabs  at  absolute  locations  specified 
by  theTabs  array 


Controls  visibility  of  the  record 
Indicates  whether  text  or  style  data 
have  changed  since  the  last  save 
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TEParamBlock  moreFlags  field  values 


fCtlTarget 
fCtlCanBeTarget 

fCtlWantsEvents 

fCtlProcRefNotPtr 

fTellAboutGrow 

fCtllsMultiPart 
colorDescriptor 

styleDescriptor 


$8000 
$4000 

$2000 
$1000 
$0800 

$0400 
$000C 

$0003 


TEParamBlock  textFlags  field  values 


fNotControl 
f SingleFormat 

f SingleStyle 

fNoWordWrap 

fNoScroll 

fReadOnly 

f SmartCutPaste 

fTabSwitch 

fDrawBounds 

fColorHilight 
fGrowRuler 


$80000000 
$40000000 

$20000000 
$10000000 
$08000000 
$04000000 
$02000000 

$01000000 

$00800000 

$00400000 
$00200000 


fDisableSelection  $00100000 
fDrawInactiveSelection  $00080000 


Record  is  target  of  user  keystrokes 
Record  can  be  target  of  user 
keystrokes— must  be  set  to  1 
Must  be  set  to  1 
Must  be  set  to  1 

Record  wants  to  know  when  the  user 

changes  the  window  size 

Must  be  set  to  1 

Indicates  type  of  reference  in 

colorRef 

Indicates  type  of  reference  in 
styleRef 


TextEdit  Record  is  not  a  control 
Only  one  ruler  is  allowed  for  record- 
must  be  set  to  1 

Only  one  style  is  allowed  for  record 

No  word  wrap  is  performed 

The  text  cannot  scroll 

Text  cannot  be  edited 

Record  supports  intelligent  cut  and 

paste 

Tab  key  switches  user  to  next  TextEdit 
record  on  the  screen 
TextEdit  draws  a  box  around  text, 
inside  the  bounding  rectangle 
Use  color  table  for  highlighting 
Adjust  right  margin  whenever  the  user 
changes  the  window  size 
User  cannot  selea  or  edit  text 
TextEdit  displays  a  box  around  an 
inactive  selection 
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Table  49-2      TextEdit  data  structures 


Name 


Offset/Value  Type 


Description 


TECol or Table 

contentColor  $0000  Word 
outiinecoior     $0002  Word 

hilightForeColor 

$0004  Word 

hilightBackColor 

$0006  Word 


vertColorDescriptor 

$0008  Word 

vertColorRef      $000A  LongWord 


horzColorDescriptor 

$000E  Word 


horzColorRef      $0010  LongWord 


growColorDescriptor 

$0014  Word 


growColorRef      $00l6  LongWord 


Color  for  inside  of  bounds  rectangle 
Color  for  outline  drawn  around  text 

Foreground  color  for  highlighted  text 

Background  color  for  highlighted  text; 
also  used  for  caret 

Specifies  type  of  reference  in 
vertColorRef 

Reference  to  color  table  for  vertical 
scroll  bar 

Specifies  type  of  reference  in 
horzColorRef 

Reference  to  color  table  for  hori2ontal 
scroll  bar 

Specifies  type  of  reference  in 
growColorRef 

Reference  to  color  table  for  size  box 


♦  Note:  All  of  the  bits  in  each  TECoiorTabie  color  word  are  significant.  TextEdit 
forms  color  patterns  by  replicating  the  appropriate  color  word  the  appropriate 
number  of  times  to  form  a  QuickDraw  n  pattem. 
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TEFormat  (format  Structure) 

$0000  Word 


version 


rulerListLength 


$0002  LongWord 


theRulerList  $0006 
styleListLength 

theStyleList 
numberOf Styles 
theStyles 


TERuler 
LongWord 

TEStyle 

LongWord 

Styleltem 


Version  number  for  format  structure- 
value  must  be  $0000 

Size,  in  bytes,  of 
theRulerList  array 
Array  of  TERuler  structures 
Size,  in  bytes,  of  thestyieList 
array 

Array  of  TEStyie  structures 
Number  of  entries  in  thestyies  array 
Array  of  style  it  em  structures 
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TEParamBiock  (parameter  block  for  creating  TextEdit  structures) 


$0000 

Word 

Niimhpr  of  naramptprs  to  follow — 

viilnpc  ranop  from  7  thronoh  9*^ 

ID 

T  r\f\d\iJ  c\T(\ 

Anniircition  ii<;<;!onpH  TF)  for  rprorH 

RoiinHinp  rprti?nplp  for  pntirp  TpxtFdit 

rprorH  inrliirlino'  ^rrol!  hijr*;  5inH 

oiiflinp<; 

procRef 

MiKt  hp  ^et  to  ^ft^OOOOOO 

f  XcL^S 

Word 

Control  fljiPS 

itioreFlags 

WUIU 

refCon 

$0016 

1?p<;prvpH  for  iinnliration  iisp 

textFlags 

$001A 

T  nnpWnrH 

TPYtFdit  rontrol  flaps 

indentRect 

$001E 

Rprt 

.Snprifips  bounding  rectangle  for  text 

in  TpytFriit  record 

vertBar 

$0026 

Hiindlp  to  vprtirjil  srroll  hjir 

vert Amount 

$002A 

Word 

Number  of  pixels  to  scroll  per  click  on 

vertical  scroll  arrows 

horzBar 

$002C 

RpcprvpH  must  hp  spt  to  NT  II I 

horzAmount 

$0030 

Word 

Reserved — must  be  set  to  $0000 

styleRef 

$0032 

Til  np  Word 

Reference  to  initial  stvle  information 

for  rprorH 

textDescriptor  $0036 

Word 

Defines  format  of  textRef 

textRef 

$0038 

LongWord 

Reference  to  initial  text  for  record 

textLength 

$003C 

LongWord 

Length  of  text  referred  to  by  textRef 

maxChars 

$0040 

LongWord 

Maximum  number  of  characters 

allowed  in  record 

maxLines 

$0044 

LongWord 

Must  be  set  to  NULL 

itiaxCharsPerLine 

$0048 

Word 

Must  be  set  to  NULL 

maxHeight 

$004A 

Word 

Must  be  set  to  NULL 

colorRef 

$004C 

LongWord 

Reference  to  the  TECoiorTabie  for 

the  record 

drawMode 

$0050 

Word 

QuickDraw  II  text  mode 

filterProcPtr 

$0052 

Pointer 

Pointer  to  filter  routine  for  the  record 

TERecord  (control  Structure  for  TextEdit  records) 

ctrlNext 

$0000 

Handle 

Handle  to  next  control  in  control  list 

inPort 

$0004 

Pointer 

Pointer  to  GrafPort  for  TextEdit 

record 

boundsRect 

$0008 

Reel 

Bounding  rectangle  for  record 
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ctrlFlag 

$0010 

Byte 

Low-order  byte  from  TEParamBiock 

flags  field 

ctrlHilite 

$0011 

Byte 

Reserved 

lastErrorCode 

$0012 

Word 

Last  error  generated  by  TextEdit 

ctrlProc 

$0014 

LongWord 

Always  set  to  $85000000 

ctrlAction 

$0018 

LongWord 

Reserved 

f ilterProc 

$001C 

Pointer 

Pointer  to  filter  procedure  for  the 

record 

ctrlRefCon 

$0020 

LongWord 

Reserved  for  application 

colorRef 

$0024 

LongWord 

Reference  to  TECoiorTabie  for 

record 

textFlags 

$0028 

LongWord 

TEParamBiock  textFlags  field 

text Length 

$002C 

LongWord 

Length,  in  bytes,  of  text  in  record 

blockList 

$0030 

TextList 

TextList  structure  describing  text 

for  the  record 

ctrllD 

$0038 

Long 

Application-assigned  ID  for  the  record 

ctrlMoreFlags 

$003C 

Word 

TEParamBiock  moreFlags  field 

Ctrl Version 

$003E 

Word 

Reserved 

viewRect 

$0040 

Rect 

Bounding  rectangle  for  text  on  screen 

totalHeight 

$0048 

LongWord 

Total  height  of  the  text  for  the  record, 

in  pixels 

lineSuper 

$004C 

SuperHandle 

Root  reference  for  text  in  record 

styleSuper 

$0058 

SuperHandle 

Root  reference  for  styles  in  record 

styleList 

$0064 

Handle 

Handle  to  list  of  unique  styles 

rulerList 

$0068 

Handle 

Handle  to  list  of  rulers 

lineAtEndFlag 

$006C 

Word 

Indicates  whether  last  character  was  a 

line  break 

selectionStart  $006E 

LongWord 

Starting  text  offset  for  current 

selection 

selectionEnd 

$0072 

LongWord 

Ending  text  offset  for  current  selection 

selectionActive 

$0076 

Word 

Indicates  whether  selection  is  active 

selectionState  $0078 

Word 

Indicates  whether  selection  is  on 

screen 

caretTime 

$007A 

LongWord 

Tick  count  for  caret  blink 

nullStyleActive 

$007E 

Word 

Indicates  whether  null  style  is  to  be 

used 

nullStyle 

$0080 

TEStyle 

Style  definition  for  null  style 

topTextOf f set 

$008C 

LongWord 

Offset  into  record  text  corresponding 

to  top  of  screen 
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topTextVPos  $0090 

vertScrollBar  $0092 
vertScrollPos  $0096 
vertScrollMax  $009A 

vertScrollAmount 

$009E 

horzScrollBar  $00A0 
horzScrollPos  $00A4 
horzScrollMax  $00A8 

horzScrollAmount 

$00AC 

growBoxHandle  $OOAE 
maximumChars  $00B2 

xnaximumLines  $00B6 
maxCharsPerLine 

$00BA 

maximumHeight  $00BC 

textDrawMode  $00BE 

wordBreakHook  $00C0 

wordWrapHook  $00C4 

keyFilter  $00C8 

theFilterRect  $OOCC 

theBufferVPos  $00D4 

theBufferHPos  $00D6 

theKeyRecord  $00D8 

cachedSelcOf f set 

$00E6 


Word 

Difference  between  top  of  text  and 

topmost  scroll  position 

T  T           J  1 

Handle 

TT           Jl             C                           1                   11  L 

Handle  of  vertical  scroll  bar 

LongWofd 

Current  vertical  scroll  position 

LongWord 

%  r        •                    11             11                         1               11  r 

Maximum  allowable  vertical  scroll  from 

top  of  text 

Word 

Number  of  pkels  to  scroll  on  each 

vertical  arrow  click 

Handle 

_  _            II             ^1            a                     t                   lit  ^ 

Handle  of  horizontal  scroll  bar  (not 

supported) 

LongWord 

Current  horizontal  scroll  position  (not 

supported) 

LongWord 

--f               II          111*            1  11 

Maximum  allowable  honzontal  scroll 

from  left  boundary  (not  supported) 

Word 

Number  of  pkels  to  saoll  on  each 

horizontal  arrow  click  (not  supported) 

Handle 

Handle  to  the  Size  box  control 

LongWord 

%  r       •                           1             r  1 

Maximum  number  of  characters 

allowed  in  the  text 

LongWord 

Maximum  number  of  lines  allowed  in 

the  text  (not  supported) 

Word 

m  r        •                                  1                r  1 

Maximum  number  of  characters 

II                         J     •                     I'                  /              A                                     _t  J\ 

allowed  in  a  line  (not  supported) 

Word 

Maximum  text  height,  in  pixels  (not 

supported) 

Word 

QuickDraw  II  drawing  mode  for  the 

text 

Pointer 

Pointer  to  routine  to  handle  word 

breaks 

Pointer 

Pointer  to  routine  to  handle  word  wrap 

Pointer 

Pointer  to  keystroke  filter  routine 

Rect 

Rectangle  for  generic  filter  procedure 

Word 

Vertical  component  of  current  position 

for  generic  filter  procedure 

Word 

Horizontal  component  of  current 

position  for  generic  filter  procedure 

KeyRecord 

Parameters  for  keystroke  filter  routine 

LongWord 

Text  offset  for  cached  caret  position 
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cachedSelcVPos 

$OOEA 

Word 

Vertical  component  of  caclied  caret 

position 

cachedSelcHPos 

$OOEC 

Word 

Horizontal  component  of  cached  caret 

position 

mouseRect 

$OOEE 

Rect 

Bounding  rectangle  for  mouse  events 

mouseTime 

$00F6 

LongWord 

Tick  count  value  when  mouse  button 

was  last  released 

mouseKind 

$OOFA 

Word 

Kind  of  last  click 

lastClick 

$OOFC 

Point 

Location  of  last  mouse  click 

savedHPos 

$0100 

Word 

Saved  horizontal  position  for  up  and 

down  arrows 

anchorPoint 

$0102 

Long 

Anchor  point  for  current  selection 

♦  Note:  TextEdit  maintains  fields  beyond  anchorPoint.  Applications  should  never 
access  these  fields  or  attempt  to  save  the  state  of  a  TextEdit  record  by  writing  and 
reading  the  public  fields  documented  here. 


TERuler  (fuler 

Structure) 

lef tMargin 

$0000 

Word 

Left  indent  pixel  count  for  all  lines 

except  those  that  start  paragraphs 

left Indent 

$0002 

Word 

Left  indent  pixel  count  for  lines  that 

start  paragraphs 

rightMargin 

$0004 

Word 

Right  text  boundary,  measured  from 

left  edge  of  text  rectangle 

just 

$0006 

Word 

Text  justification  flag 

extraLS 

$0008 

Word 

Spacing  between  lines  (in  pixels) 

flags 

$000A 

Word 

Control  flags  for  the  ruler 

userData 

$000C 

LongWord 

Reserved  for  application  use 

tabType 

$0010 

Word 

Indicates  type  of  tabs  used 

theTabs 

$0012 

Tabltem 

Array  of  Tabitems,  one  for  each 

absolute  tab  stop 

tabTerminator 

Word 

Either  the  spacing  for  standard  tabs  or 

a  flag  terminating  theTabs  array 

TE  Style  (style 

description  structure) 

fontID 

$0000 

LongWord 

FontID  for  text  using  this  style 

f oreColor 

$0004 

Word 

Foreground  color  for  the  style 

backColor 

$0006 

Word 

Background  color  for  the  style 

userData 

$0008 

LongWord 

Reserved  for  application  use 
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KeyRecord 


theChar 

$0000 

Word 

Character  value  to  translate 

theModif iers 

$0002 

Word 

Modifier  key  state  bit  flag  (see 

Chapter  7,  "Event  Manager,"  for 

information  on  key  modifiers) 

thelnputHandle  $0004 

Handle 

Handip  to  rharartpr  in  text 

cursorOf f set 

$0008 

LongWofd 

New  cursor  location 

theOpCode 

$0O0C 

Word 

Operation  code  for  key  filter  routine 

styieitem  (style  reference  structure) 

1  onrrt*  H 

$0000 

LongWord 

Number  of  text  characters  using  the 

style 

offset 

$0004 

LongWord 

Byte  offset  into  theStyleList  to 

entry  that  defines  the  style  for  this  tex 

SuperBlock 

$0000 

Handle 

• 

Handle  to  next  SuperBiock  in  list 

prevHandle 

$0004 

Handle 

Handle  to  previous  SuperBiock  in 

hst 

textLength 

$0008 

LongWord 

Number  of  bytes  of  text  for  this 

SuperBiock 

$000C 

LongWord 

Reserved 

the Items 

$0010 

Superltem 

Array  of  Superitems  for  this  block 

SuperHandle 

cachedHandle 

$0000 

Handle 

Handle  to  the  current  SuperBiock 

cachedOf f set 

$0004 

LongWord 

Text  offset  to  the  start  of  the  current 

SuperBiock 

cachedlndex 

$0008 

Word 

Index  value  for  current  SuperBiock 

itemsPerBlock 

$000A 

Word 

Number  of  Superitems  per 

SuperBiock 

Superltem 

length 

$0000 

LongWord 

Number  of  bytes  of  text  for  this 

Superltem 

data 

$0004 

LongWord 

Data  for  the  Superltem 
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Tabitem  (tab  Stop  descriptor) 


tabKind 

$0000 

Word 

Must  be  set  to  $0000 

tabData 

$0002 

Word 

Pixel  offset  to  the  tab  stop  from  left 

boundary  of  text  rectangle 

TextBlock 

nextHandle 

$0000 

Handle 

Handle  to  next  TextBlock  in  list 

prevHandle 

$0004 

Handle 

Handle  to  previous  TextBlock  in  list 

textLength 

$0008 

LongWord 

Number  of  bytes  of  text  in  theText 

flags 

$000C 

Word 

Reserved 

$000E 

Word 

Reserved 

theText 

$0010 

Byte 

textLength  bytes  of  text 

TextList 

cachedHandle 

$0000 

Handle 

Handle  to  the  current  TextBlock 

cachedOf f set 

$0004 

LongWord 

Text  offset  to  the  start  of  the  current 

TextBlock 
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m  Table  49-3      TextEdit  error  codes 

Code  Name 

$2201  teAlreadyStarted 

$2202  teNotStarted 

$2203  telnvalidHandle 

$2204  telnvalidDescriptor 

$2205  telnvalidFlag 

$2206  telnvalidPCount 

$2207  Reserved 

$2208  teBufferOverflow 

$2209  telnvalidLine 


$220A  telnvalidCall 

$220B  telnvalidParameter 
$220C  teInvalidTextBox2 


Description 

TextEdit  has  already  been  started 

TextEdit  has  not  been  started 

The  teHandle  parameter  does  not  refer 

to  a  valid  TERecord 

Invalid  descriptor  value  specified 

Specified  flag  word  is  invalid 

Invalid  parameter  count  value 

specified 

Reserved 

The  output  buffer  was  too  small  to 
accept  all  data 

Starting  line  value  is  greater  than  the 
number  of  lines  in  the  text  (can  be 
interpreted  as  end-of-file  in  some 
circumstances) 

This  call  is  not  allowed  for  the  supplied 
TERecord 

A  passed  parameter  was  invalid 
The  TextBox2  format  codes  were 
inconsistent 
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Chapter  50  Text  Tool  Set  Update 


This  chapter  documents  new  features  of  the  Text  Tool  Set.  The  complete 
reference  to  the  Text  Tool  Set  is  in  Volume  2,  Chapter  23  of  the 
A^le  IIGS  Toolbox  Reference. 
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New  features  in  the  Text  Tool  Set 

The  following  information  describes  new  features  in  this  version  of  the  Text  Tool  Set. 

The  Text  Tool  Set  now  supports  the  Slot  Arbiter.  All  set  device  calls  (such  as 
SetOutputDevice,  setinputDevice,  and  SO  forth)  accept  slot  numbers  1  through  7 
or  9  through  15.  Previously,  the  external  slots,  slots  9  through  15,  were  not  valid  for  these 
calls.  If  your  application  specifies  an  external  slot,  the  Text  Tool  Set  will  route  the  calls  as 
appropriate.  If  your  application  specifies  a  slot  from  1  through  7,  the  Text  Tool  Set 
determines  whether  the  slot  is  internal  or  external,  and  routes  the  calls  to  the  appropriate 
firmware. 

Note  that  all  get  device  calls  still  retum  slot  numbers  in  the  range  from  1  through  7,  in  order 
to  maintain  compatability  with  existing  code. 
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Chapter  51  Tool  Locator  Update 


This  chapter  documents  new  features  of  the  Tool  Locator.  The  complete 
reference  to  the  Tool  Locator  is  in  Volume  2,  Chapter  24  of  the 
Apple  IIGS  Toolbox  Reference. 
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New  features  in  the  Tool  Locator 

This  section  explains  new  features  of  the  Tool  Locator. 

■  The  Tool  Locator  uses  a  new  algorithm  to  load  tools  from  disk.  It  will  load  tools  from 
disk  only  if  it  cannot  find  a  tool  in  ROM  with  a  version  number  as  high  as  the  requested 
version.  The  Tool  Locator  makes  no  assumptions  about  which  tools  are  in  ROM  and 
which  are  on  the  system  disk. 

For  every  tool  that  is  to  be  loaded,  the  Tool  Locator  makes  a  version  call.  If  the  version 
call  returns  an  error  because  the  tool  is  not  present,  or  the  resulting  version  number  is 
too  low,  then  the  tool  is  loaded  from  the  system  disk. 

■  The  Tool  Locator  no  longer  unloads  all  RAM-based  tools  every  time  TLShutDown  is 
called.  Instead,  it  returns  the  system  to  a  default  state,  set  by  a  new  call  in  the  Tool 
Locator,  setoef  auitTPT.  This  call  can  make  any  collection  of  RAM  and  ROM  tools 
the  default  state.  The  system  returns  to  the  default  state  when  TLShutdown  is  called. 


Tool  set  startup  and  shutdown 

The  Tool  Locator  now  provides  calls  that  automatically  start  and  stop  specified  tool  sets 
in  the  correct  order.  These  calls,  startupToois  and  shutoownToois,  are  documented 
in  "New  Tool  Locator  calls"  later  in  this  chapter. 

The  StartupToois  Call  performs  the  following  steps  during  startup  processing: 

1)  Starts  the  Resource  Manager 

2)  Opens  the  resource  fork  for  the  current  application 

3)  Obtains  memory  for  the  application's  direct  page 

4)  Starts  the  tools  specified  in  the  input  startstop  record;  updates  the  startstop 
record  as  appropriate 

5)  Returns  the  startstop  record  reference  to  the  calling  program 

Your  application  must  pass  this  returned  startstop  record  reference  to 
shutDownToois  at  tool  shutdown  time. 
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startupToois  sets  some  tool  set  default  values  for  you.  If  these  value  are  not 
appropriate  for  your  application,  you  should  change  them  by  issuing  the  appropriate  tool 
calls  after  startupToois  has  returned: 

QuickDraw  n  Started  with  the  video  mode  from  the  input 

startstop  record— the  QDStartup  maxWidth 
parameter  is  set  to  160  bytes. 

System  calls  waitcursor;  your  application  must 
change  the  cursor  to  an  arrow  before  accepting  user 
input. 

Queue  size  set  to  20,  maximum  mouse  clamp  set  to 
either  320  or  640,  depending  upon  the  video  mode 
specified  in  the  startstop  record. 

Update  rate  set  to  0  (use  default  Note  Synthesizer  rate), 
incren^nt  set  to  20,  and  interrupts  have  been  disabled 
(the  system  calls  stopints).  Your  program  must  enable 
interrupts  with  startints.  The  Note  Sequencer  will 
automatically  start  the  Sound  Tool  Set  and  the  Note 
Synthesizer,  if  you  have  not  included  them  in  your 
startstop  record. 

shutDownToois  performs  the  following  steps  during  tool  set  shutdown: 

1)  Shuts  down  tools  specified  in  input  startstop  record 

2)  Disposes  of  handle  to  direct  page 

3)  Disposes  of  handle  to  startstop  record  (unless  pointer  was  passed) 

4)  Shutsdown  the  Resource  Manager 


QuickDraw  n  Auxiliary 


Event  Manager 


Note  Sequencer 


Chapter  51  Tool  Locator  Update 


51-3 


Apple  UGS  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


Both  these  calls  require  that  your  application  format  a  tool  start  stop  record.  That 
record  is  defined  as  follows: 


■   Figure  51-1     Tool  set  StartStop  record 


$00 

flags 

Word— Flag  word— must  be  set  to  0 

$02 

vldeoMode 

Word— Video  mode  for  QuickDraw  II 

$04 

resFilelD 

Word— Set  by  StartUpTools 

$06 

dPageHandle 

Long— Set  by  StartUpTools 

$0A 

numTools 

Word— Number  of  entries  in  toolArray 

$0C 

tool Array 

numTool  s  TooiSpec  records 

videoMode        Defines  the  video  mode  for  QuickDraw  H.  See 

Chapter  l6,  "QuickDraw  11,"  in  the  Toolbox  Reference  for  valid  values. 

resFiieiD        The  StartUpTools  call  sets  this  field.  shutDownToois  requires  it 
as  input. 

dPageHandle      The  StartUpTools  call  sets  this  field.  ShutDownToois  requires  it 
as  input. 


514 


Apple  IIGS  Toolbox  Reference,  Volume  3 


Apple  lies  Toolbox  Reference,  Volume  3 


Beta  Draft 


30  August  1989 


tooiArray        Each  entry  defines  a  tool  set  to  be  started.  The  numToois  field 

specifies  the  number  of  entries  in  this  array.  Each  entry  is  formatted  as 
follows: 


$00 

toolNumber 

$02 

minVersion 

Word— Tool  set  identifier 

Word— Minimum  acceptable  tool  set  version 


toolNiimber 


toolVersion 


Specifies  the  tool  set  to  be  loaded  Valid  tools  set  numbers  are 
listed  in  Table  51-1. 

Specifies  the  minimum  acceptable  version  for  the  tool  set.  See 
Chapter  24,  "Tool  Locator,"  in  the  Toolbox  Reference  for  the 
format  of  this  field. 
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Tool  set  numbers 

Table  51-1  lists  the  tool  set  numbers  for  all  tool  sets  supported  by  the  startupToois 
and  shutDownToois  calls. 


■  Table  51-1      Tool  set  numbers 


Tool  set  number 

Tool  set  name 

#01 

Tool  Locator 

#02 

Memorv  Manager 

#0^ 

Miscellaneous  Tool  Set 

#04 

QuickDraw  II 

#os 

Desk  Manacer 

•pUD 

Fvent  Manaeer 

$07 

#07 

Scheduler 

#08 

Sound  Tool  Set 

#09 

Apple  Desktop  Bus  Tool  Set 

#10 

SANE  Tool  Set 

#11 

Integer  Math  Tool  Set 

$or 

#12 

Text  Tool  Set 

#13 

Reserved  for  internal  use 

#14 

Window  Manager 

$0F 

#15 

Menu  Manager 

$10 

#16 

Control  Manager 

$11 

#17 

System  Loader 

$12 

#18 

QuickDraw  n  Auxiliary 

$13 

#19 

Print  Manager 

$14 

#20 

LineEdit  Tool  Set 

$15 

#21 

Dialog  Manager 

$16 

#22 

Scrap  Manager 

$17 

#23 

Standard  File  Operations  Tool  Set 

$18 

#24 

Not  available 

$19 

#25 

Note  Synthesizer 

$1A 

#26 

Note  Sequencer 

$1B 

#27 

Font  Manager 

$1C 

#28 

List  Manager 
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$1D  #29 

$1E  #30 

$20  #32 

$22  #34 


Audio  Compression  (ACE) 
Resource  Manager 
MIDI  Tool  Set 
TextEdit  Tool  Set 
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Tool  set  dependencies 

Although  startupToois  handles  the  order  of  tool  startup  for  you,  it  does  not  manage 
tool  set  dependencies,  It  is  your  responsibility  to  specify  all  required  tool  sets  in  order  to 
ensure  correct  system  operation.  Table  51-2  documents  current  tool  set  dependencies. 


Table  51-2      Tool  set  dependencies 


Tool  set  and  number 


Depends  upon 


Tool  Locator(#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 

QuickDraw  II  (#04) 


Desk  Manager  (#05) 


Event  Manager  (#06) 
Scheduler  (#07) 
Sound  Tool  Set  (#08) 


Apple  Desktop  Bus  (#09) 
SANE  Tool  Set  (#10) 


No  dependencies;  always  started  first 
Tool  Locator  (#01) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 

Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  n  (#04) 
Event  Manager  (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
LineEdit  (#20) 
Dialog  Manager  (#21) 
Scrap  Manager  (#22) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
Tool  Locator  (#01) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
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Integer  Math  Tool  Set  (#11) 
Text  Tool  Set  (#12) 
Window  Manager  (#14) 


Menu  Manager  (#15) 


Control  Manager  (#l6) 


Tool  Locator  (#01) 
Tool  Locator  (#01) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  n  (#04) 
Event  Manager  (#06) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
LineEdit  (#20) 
Font  Manager  (#27) 
Resource  Manager  (#30) 

Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  H  (#04) 
Event  Manager  (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Resource  Manager  (#30) 

Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  II  (#04) 
Event  Manager (#06) 
Window  Manager  (#14) 
Menu  Manager  (#15) 
Resource  Manager  (#30) 


For  AlertWindow  call 
For  AlertWindow  call 
Only  if  you  use 
resources 


Only  if  you  use 
resources 


Only  if  you  use 
resources  or  icon 
buttons 


♦  Note.  You  should  consider  the  Window,  Control,  and  Menu  managers  as  one  unit,  and 
always  start  them  together  and  in  that  order. 


System  Loader  (#17) 


Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
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QuickDraw  n  Auxiliary  (#18)      Tool  Locator  (#01) 

Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  E  (#04) 
Font  Manager (#27) 


♦  Note.  QuickDraw  II  Auxiliary  uses  the  Font  Manager  in  the  picture  drawing  routines. 
For  proper  operation,  you  should  start  the  Font  Manager  before  using  the  QuickDraw 
n  Auxiliary  picture  routines;  however,  the  picture  routines  will  not  fail  if  the  Font 
Manager  is  not  present. 


Print  Manager  (#19) 


LineEdit  Tool  Set  (#20) 


Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  II  (#04) 
QuickDraw  n  Auxiliary  (#18) 
Event  Manager  (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
LineEdit  (#20) 
Dialog  Manager  (#21) 
List  Manager  (#28) 
Font  Manager  (#27) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  U  (#04) 
Event  Manager  (#06) 
QuickDraw  n  Auxiliary  (#18) 
Scrap  Manager  (#22) 
Font  Manager  (#27) 


For  Text2  items  only 
For  Text  2  items  only 
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Dialog  Manager  (#21) 


♦ 

Scrap  Manager  (#22) 
Standard  FUe  Tool  Set  (#23) 

Note  Synthesizer  (#25) 
Note  Sequencer  (#26) 


Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  n  (#04) 
Event  Manager (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
QuickDraw  U  Auxiliary  (#18) 
LineEdit  (#20) 
Font  Manager  (#27) 


Tool  Locator  (#01) 
Memory  Manager  (#02) 

Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  E  (#04) 
Event  Manager  (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
LineEdit  (#20) 
Dialog  Manager  (#21) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Sound  Tool  Set  (#08) 

Tool  Locator  (#01) 
Memory  Manager  (#02) 
Sound  Tool  Set  (#08) 
Note  Synthesizer  (#25) 


For  Text2  items  only 
For  Text2  items  only 


Note.  LineEdit  and  Dialog  Manager  require  Font  Manager  and  QuickDraw  n  Auxiliary  if 
you  use  LETextBox2  or  LongstatText2  which  require  any  font  styling  (for 
example,  outline,  boldface,  and  so  on). 


♦  Note.  The  Note  Sequencer  automatically  handles  the  startup  and  shutdown  of  the 
Sound  Tool  Set  (#8)  and  the  Note  Synthesizer  (#25). 
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Font  Manager  Tool  Locator  (#1) 

Memory  Manager  (#2) 

Miscellaneous  Tool  Set  (#3)  For  chooseFont  only 
QuickDraw  II  (#4) 

Integer  Math  (#11)  For  ChooseFont  only 

Window  Manager  (#14)  For  chooseFont  only 

Control  Manager  (#16)  For  ChooseFont  only 

Menu  Manager  (#15)  For  FixFontMenu  only 

List  Manager  (#28)  For  FixFontMenu  and 

ChooseFont  only 
LineEdit  (#20)  For  ChooseFont  only 

Dialog  Manager  (#21)  For  ChooseFont  only 

Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  H  (#04) 
Event  Manager (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Tool  Locator  (#01) 
Memory  Manager  (#02) 
Miscellaneous  Tool  Set  (#03) 
Sound  Tool  Set  (#8) 

Note  Synthesizer  (#25)  For  time-stamping 

only 

♦  Note.  The  MIDI  Tool  Set  requires  the  Note  Synthesizer  in  order  to  support  the  MIDI 
clock  feature.  If  you  are  not  using  MIDI  clock,  the  Note  Synthesizer  is  not  required. 

Resource  Manager  (#30)  Tool  Locator  (#01) 
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TextEdit  Tool  Set  (#34) 


Tool  Locator  (#01) 
Miscellaneous  Tool  Set  (#03) 
QuickDraw  II  (#04) 
QuickDraw  11  Auxiliary  (#18) 
Event  Manager (#06) 
Window  Manager  (#14) 
Control  Manager  (#16) 
Menu  Manager  (#15) 
Scrap  Manager  (#22) 
Font  Manager  (#27) 
Resource  Manager  (#30) 


Version  $0300 
Version  $0300 
Version  $0300 
Version  $0206 
Version  $0300 
Version  $0300 
Version  $0300 
Version  $0300 
Version  $0104 
Version  $0204 
Version  $0100 
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New  Tool  Locator  calls 

The  call  setDef  auitiPT  has  been  added  to  the  Tool  Locator  to  facilitate  permanent 
tool  patches.  startupToois  and  shutDownToois  provide  automatic  services  for 
bringing  up  or  removing  tool  sets.  The  MessageByName  tool  call  provides  facilities  for 
your  application  to  use  the  message  center. 


MessageByName  $1701 

Creates  and  associates  a  name  with  a  new  message,  providing  a  convenient  and  extensible 
mechanism  for  creating,  tracking,  and  passing  messages  between  programs.  Your 
application  can  then  use  the  other  Message  Center  Tool  Locator  calls  to  manipulate  or 
delete  the  message. 

Parameters 

Stack  before  call 

Previous  contents 

Space      -  Long— Space  for  result 

createltFlag  Word— Boolean;  create  message? 

-  recordPointer  -  Long— Pointer  to  input  record 

~  <— SP 

Stack  after  call 


Previous  contents 


-  responseRecord  - 


Long— Response  record  from  call 
<— SP 
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Errors 


$0111 


messageNotFound 


$0112  messageOvfl 
$0113  nameTooLong 
Memory  Manager  errors 


No  message  found  with  specified 
name 

No  message  numbers  available 
Message  name  too  long 
Errors  from  NewHandie  returned 
unchanged 


extern  pascal  responseRecord 

MessageByName (createltFlag, 
recordPointer) ; 


Boolean 
Pointer 


createltFlag; 
recordPointer; 


createltFlag         Determines  whether  to  create  a  message  containing  the  information 
from  the  input  record.  If  there  is  no  existing  message  with  the 
specified  name,  then  the  setting  of  createltFlag  governs  whether  to 
create  a  message.  If  there  is  already  a  message  with  the  specified 
name,  then  the  setting  of  createltFlag  determines  whether  to  replace 
that  existing  message  with  a  new  one  based  upon  the  input  record. 

recordPointer      Pointer  to  an  input  record,  which  defines  the  content  and 
characteristics  of  the  new  message: 


$00 

—          blookLen  — 

Word— Length  of  record  (including  blockLen) 

$02 

naraeStrlng 

n  Bytes-4dentlfier  string  for  the  message 

$02+n 

dataBlock 

m  Bytes— Optbnai  data  for  message 

blockLen         Contains  the  length,  in  bytes,  of  the  input  record.  Note  that  the 
value  for  this  field  includes  the  length  of  blockLen, 
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namestring      The  identifier  for  the  new  message.  This  is  a  standard  Pascal 
string  (length  byte  followed  by  ASCII  data),  with  a  maximum 
length  of  64  bytes  (not  including  the  length  byte).  In  order  to 
prevent  message  name  conflict,  this  name  string  should  contain 
the  the  manufacturer's  name,  followed  by  the  product  name 
and/or  code,  followed  by  a  unique  identifying  string.  You  may 
set  the  high-order  bits  of  each  byte;  note,  however,  that  the 
system  does  not  include  these  bits  in  name  comparisons. 

dataBiock        Application-defined  data  that  are  copied  into  a  created 
message.  Use  of  this  field  is  optional. 

responseRecord      Contains  the  response  information  from  the  call: 


$00 

createFlag 

$02 

messagelD 

Word— Boolean;  was  message  aeated? 
Word— ID  number  for  aeated  message 


createFlag      Indicates  whether  MessageByName  created  a  message.  Note 
that  if  you  set  createltFlag  to  TRUE  on  input  to 
MessageByName,  and  there  was  already  a  message  with  the 
specified  namestring  in  the  Message  Center,  then  this  flag  will 
be  FALSE,  and  messagelD  will  identify  the  message  into  which 
your  dataBiock  was  copied. 

messagelD "      Message  ID  for  new  mesage,  if  MessageByName  created  one. 
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SetDefaultTPT  $l601 

Sets  the  default  Tool  Pointer  Table  (TPT)  to  the  current  TPT,  Used  to  permanendy  install  a 
tool  patch. 

A  Warning     An  application  should  not  make  this  call.A 
Parameters        This  call  has  no  input  or  output  parameters.  The  stack  is  unaffected. 

C  extern  pascal  void  SetDefaultTPT () ; 
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ShutDownTools  $1901 

Shuts  down  the  tools  specified  in  the  input  start  stop  record. 

Your  program  must  pass  the  startstop  record  reference  that  was  returned  by 
StartUpTools. 

Parameters 

Stack  before  call 


Previous  contents 


startStopDesc 


-  startStopRecRef  - 


Stack  after  call 


Word— Defines  the  type  of  reference  stored  in  startStopRecRef 
Long— Reference  to  the  startstop  record 
<— SP 


PretHous  contents 


Errors 
C 


StartStopDesc 


StartStopRecRef 


None 


<— SP 


extern  pascal  void  ShutDownTools (startStopDesc, 
StartStopRecRef) ; 

Word  StartStopDesc; 
Long  StartStopRecRef; 

Defines  the  type  of  reference  stored  in  startStopRecRef. 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

Reference  to  the  updated  startstop  record  returned  by 
StartUpTools. 
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StartUpTools  $1801 


Starts  and  loads  the  tools  specified  in  the  input  startstop  record.  Upon  successful 
return  from  startupToois,  the  specified  tools  will  have  been  started  and  the  cursor  will 
be  represented  by  the  watch  image  (if  QuickDraw  II  Auxiliary  was  loaded).  Your  program 
should  change  the  cursor  image  before  accepting  user  input. 

Your  program  must  pass  the  startstop  record  reference  that  was  returned  by 
StartupToois  to  the  shutDownToois  call  at  tool  shutdown  time. 

Parameters 

Stack  before  call 


Previous  contents 


Space 


userlD 


startStopDesc 


-  startStopRecRef  - 


Stack  after  call 


Long— Space  for  result 

Word— Application  User  ID  for  system  calls 

Word— Defines  the  type  of  reference  stored  in  startStopRecRef 

Long— Reference  to  the  startstop  record 
<— SP 


Pretnous  contents 


-startStopRecRefRet- 


Errors 


$0103 
$0104 


Long— Reference  to  resulting  startstop  record 
<— SP 


TLBadRecFlag 
TLCantLoad 


startstop  record  invalid 
A  tool  cannot  be  loaded-check 
input  startstop  record  for 
valid  tool  numbers,  and  versions, 
and  for  correct  numioois  value 


System  Loader  errors 
Memory  Manager  errors 
GS/OS  errors 


Returned  unchanged 
Returned  unchanged 
Returned  unchanged 
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C  extern  pascal  long  StartUpTools (userlD, 

startStopDesc,   startStopRecRef ) ; 

Word  userlD,  startStopDesc; 

Long  StartStopRecRef; 

StartStopDesc       Defines  the  type  of  reference  stored  in  startStopRecRef. 

0  Reference  is  a  pointer 

1  Reference  is  a  handle 

2  Reference  is  a  resource  ID 

startStopRecRefRet  Reference  to  the  updated  startstop  record.  Your  application  must 
pass  this  record  to  the  shutoownToois  tool  call.  If  the  input  record 
reference  to  start upToois  was  a  pointer,  then  this  reference  is  also 
a  pointer.  If  the  input  reference  was  either  a  handle  or  a  resource  ID, 
then  StartUpTools  returns  a  handle. 
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